Queries maintained by Confluence administrators are parameterized and executed using the PocketQuery macro. This page describes its features.


Embedding the Macro

Within any Confluence page or blog post, you can embed this Macro with the {} syntax or using the macro editor.

Macro parameters

The PocketQuery macro has different parameters that control how database contents are to be presented in the view of the page. Some of these parameters are only available if other parameters are checked.

These are the parameters:

The following wildcards can be given as parameters:

These wildcards will be replaced by the actual content before the query is executed. Furthermore, the wildcards specific to the datasource can be used, e.g. '%' for SQL databases.

For users that are not logged into Confluence @username, @userfullname and @usermail will return "anonymous".

Dynamic load

If the option "Load macro dynamically" is enabled, the page that contains the PocketQuery won't have to wait for the PocketQuery data to be loaded. Instead, the page will completely load first and PocketQuery will fetch its data in the background, showing a loading icon in the meantime.

This will be a tremendous performance improvement if your results are comprising in size. Also, this option can be very handy if combined with dynamic parameters and the "change params template" (see below) which enables live changes to the contents currently shown without having to reload the page. 

Dynamic parameters

If you want to parameterize a PocketQuery macro dynamically when the page is loaded, you can make use of the Enable dynamic parameters feature (i.e. check the Enable dynamic parameters checkbox in the macro parameters, as described above). Then, dynamic parameters can be passed as GET parameters to the page URL. They have to be addressed using their name specified in the PocketQuery administration prefixed with 'pq_' to avoid naming collisions.

For example, if you have a macro for a query with two query parameters min and max, you can open your page like this: <your-confluence-page-url>?pq_min=10&pq_max=50. Note that GET-Parameters override the values you specified in the macro.

Note that if you use special characters or wildcards within the parameter value, you need to URL encode them. For example, the wildcard symbol '%' becomes '%25':

If you have multiple PocketQuery macros on one page that have a parameter with the same name, the GET parameter will set all these parameter values. This can be a useful feature, but be aware of unwanted name conflicts.

If you additionally check the “Use change params template” option, a form will be shown above the result that enables to change the parameters in the page.

If you additionally check the “Load macro dynamically” option, the parameters will be given to the Ajax call and results will be according to these parameters as well. It makes much sense to combine this with the “change params template” because users can simply change the parameters in the form and a submit won’t trigger a reload of the page, but will show the updated results directly in the page. In that case, the URL will also change dynamically for permalink ability and not to lose the browser history (“back” and “forward” buttons).

Example usage: Dynamic parameters generally enable a big set of possibilities, e.g.: