The Qpid Broker for Java provides a powerful feature called the Query API. This allows the retrieval of the existing configured objects attributes satisfying user-provided queries. Developers and operators can use this feature to monitor the Broker. For example, using Query API one can find all queues with queue depth exceeding some limit or existing connections made from a particular location(s).

When using the Query API one specifies the category of the object to query, a list of attributes to return in the result set, an optional where clause, expressed as a predicate, that determines the filtering criteria, ordering, and limit/offset. The features should be readily recognisable to anyone who has has familiarity with SQL. Queries associate with either the broker as a whole, or an individual virtualhost. Queries associated with the Broker can query any object within the Broker. Queries associated with a virtualhost are limited to the objects of the virtualhost itself. For instance a queue query associated with a virtualhost queries only the queues belonging to that virtualhost. On the other hand, a queue query associated with the Broker sees all the queues belonging on the entire Broker. Query API URL Description /api/latest/querybroker/<configured object category name> /api/<version>/querybroker/<configured object category name> Query API URL fragment to query the specified object type across the entire broker /api/latest/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name> /api/<version>/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name> Query API URL fragment to query the specified object type for a specific virtualhost The QueryAPI accepts select, where, orderBy, limit and offset request parameters. Parameter Name Parameter Description select The select defines the columns of the result set. It is a comma-separated list of expressions. At its most simple, an expression can be the name of the attribute (e.g. queueDepthBytes), but more complex expressions are also supported. Columns within the result set are named. For expressions that are simple attribute names, the column names will follow the attributes themselves. By default, other expressions will have a no name. Column names can be overridden with an AS clause e.g. now() AS currentDate where The where provides a boolean expression defining the result set filtering. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax and is similar to selector expressions in JMS e.g. queueDepthBytes > 16384 AND name like '%flow_queue'. orderBy Ordering conditions; the syntax of the expression is based on a subset of the SQL92 ordering expression syntax. Similar to ordering expressions in SQL, one can specify in ordering expression attributes names, sub-expressions or indexes (starting from 1) of attributes or expressions specified in select. limit The maximum number of results to provide starting from given offset. offset An offset in results (default is 0) to provide results from. GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1

The Query API returns a JSON response. The response contains the following: headers ordered list of result set column names derived from the select clause. Note that anonymous expressions (that is, those expressed without an AS) will have empty column name. results two dimensional array containing the result-set total The total number of results matching the where criteria. GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1 { "headers" : [ "name", "queueDepthBytes", "queueDepthMessages" ], "results" : [ [ "foo", 312, 26], [ "bar", 300, 24 ] ], "total" : 2 }

Expressions within the select, where and orderBy clauses can be comprised in the following manner. Expressions can be nested to arbitary depth. Parentheses allow for precedence to be explicitly denoted. variable name which can be an attribute name e.g queueDepthBytes or a reference to a parent attribute $parent.name literal e.g. 3 or 'foo' functions - see below e.g. now() or to_string(createdDate, '%tm/%td/%ty', 'EST') arithmetic operations e.g. 3 * 4 or to_string(now()) + name The following functions are supported: Function Name Function Description concat(obj[,obj..]) concatenates the given objects into a string now() returns current date and time to_date(object) converts the first parameter, which must be a string. into a date. The string must be in ISO-8601 format e.g. 1970-01-01T10:00:00Z. date_add(object, duration) adds the given ISO-8601 duration duration e.g. P1D or -PT10H to the date provided by the first parameter. to_string(object[, format[, timezone]]) Converts given object into a string. If the format argument is present, it must be a Java Formatter compliant string e.g. %f or %tY-%tm-%td. The timezone argument is significant if the object is a Date. If the timezone argument is specified it must be a valid Java timezone name. The date is converted to the specified timezone before being formatted by theformat. If the timezone is omitted UTC is assumed.