Example: CQL Function Search all pages that contain a specific label

Note: In ScriptRunner for Confluence Data Center, you can create custom CQL Functions that perform advanced searches for content in Confluence. Although this exact functionality in Cloud does not exist, you can create a custom macro that performs the same way by including code and macro parameters. For more information, check out:

To set up a custom macro that searches all pages that contain a specific label, follow these steps:

Select Create Custom Macro.

Fill out the fields that appear:

Macro Name: CQL Function - Search for label
Description: Use this macro to search all pages that contain a specific label
Enabled (radio button): Select Enabled.
Body Type: None.
Output Type: Block
Script to Execute: Enter the script for the macro here.

import com.atlassian.confluence.rest.clientv1.model.ContentArray
 
def label = parameters.get("label")
if (!(label instanceof String)) {
 return "Please provide a valid label to search for."
}
def cql = "label=${label}"
def searchResult = get("/wiki/rest/api/content/search")
        .queryString("cql", cql)
        .asObject(ContentArray).body
 
if (!searchResult || !searchResult.results) {
 return "No pages found with label '${label}'."
}
 
def contents = searchResult.results
def nextUrl = searchResult._links?.next
 
while (nextUrl) {
 def nextContents = get("/wiki${nextUrl}").asObject(ContentArray).body
    contents += nextContents.results
    nextUrl = nextContents._links?.next
}
 
def pages = contents.findAll { it.type == "page" }
 
if (pages.isEmpty()) {
 return "<p>No pages found with label '${label}'.</p>"
}
 
def html = new StringBuilder("<ul>")
pages.each { page ->
 def link = "/wiki${page._links.webui}"
    html.append("<li><a href=\"${link}\">${page.title}</a></li>")
}
html.append("</ul>")
 
return html.toString()

Select Add Parameter.
1. Type: string
2. Name: label
3. Description: Enter the label to search for pages.
4. Required: Check.
5. Hidden: Do not check.
6. Select Add.
Select Save.

You can now use this macro on a Confluence page. When you add the macro to a page, here is what appears:

For this example, we'll search for the documentation label. Here is the result:

Tip: For help with using the macro, check out the Use Macros section of the Macros documentation.