CQL Search Macro

You can add the CQL Search macro to a Confluence page. If you provide the CQL query, the macro executes the search and returns the results as links to pages.

The macro is useful to show the results of complex queries on pages, labels, and other Confluence content.

Tip: For more information about using CQL, check out CQL Guide.

Enable and disable the macro

Even though you cannot edit the CQL Search macro, you can enable and disable it.

Navigate to General Configuration → ScriptRunner → Macros, and then select the Actions menu.

From there, you can either enable or disable the macro. If you disable it, it cannot be added to pages in your Confluence instance.

Walkthrough

Watch our video to see the CQL Search macro in action.

Use the macro on a Confluence page

To use this macro, follow these steps:

Open the Confluence page you want to work with and go into edit mode.
Select Insert and then Other Macros.
When you search CQL in the search bar, CQL Search appears. Select it.
Enter the CQL statement you want to search in CQL and how many results you want to see in Max Results.
Select Preview to preview the query.
Select Insert to complete the macro.

Example

In this example, we will add links to meeting notes from the Meeting Notes space to a Meetings Guide page in the New Starter Guide space..

Open the Meetings Guide page in the New Starter Guide space.
Seach for the CQL Search macro from the Other Macros menu.
Enter the CQL query. Since we want to include every page in the space, we use the CQL query space = meeting.
Leave Max Results blank so it adds all pages.
Select Insert.

In edit mode, the CQL Search macro looks like this:

Once you Publish or Save the page, it looks like this:

Note the Prev and Next buttons to navigate results.