Canned Search for Confluence Cloud

User Guide for CQL Counter Macro

Introduction


The CQL Counter Macro displays the number of search results returned by a predefined CQL query.

image-20261101-204325.png

It includes the following features:

  • Display the count in large text with optional footer text.

  • Customisable background colour and card size.

  • Support dynamic variables in the CQL query. See Convenient Search with placeholders for the full list.


Configuration


Configure the query

  1. Insert or edit CQL Counter Macro.

  2. On the Query tab, choose Basic or CQL.

    1. Configure your search:

      • Basic mode: Select the relevant spaces, contributors, content types, labels, and date range. Enable Titles only to search titles without searching the body text.

      • CQL mode: Enter a valid CQL query. Use $$query$$ wherever reader-entered search text should be substituted. For example:

        type = page AND space = $$space.key$$ AND title ~ $$query$$ ORDER BY title
        
    2. Check the live preview to verify that the search returns the expected content and that the selected columns display the correct information.

Query settings reference

Basic mode
image-20261102-073442.png

Field

Required

Default

Description

Notes

Search Query

No

Empty

Sets the initial search text used when the macro loads.

This is the same value as Default Search Term on the Display tab.

Titles only

No

Off

Searches titles instead of content.

Generates title ~ $$query$$ when enabled and text ~ $$query$$ when disabled.

Spaces

No

All accessible spaces

Limits results to selected spaces.

Search by space name or key. Multiple spaces generate one space IN (...) condition.

Content Type

No

All supported types

Limits results to Pages, Blog posts, Attachments, or Comments.

Multiple types generate one type IN (...) condition.

Labels

No

Any label

Limits results to content with selected labels.

One label generates label = ...; multiple labels generate label IN (...).

Last Modified

No

Any time

Limits results by their last-modified date.

Options are Any time, Last 24 hours, Last week, Last month, Last year, and Custom.

From

Conditional

One month before the current date

Sets the start of a custom last-modified range.

Used only when Last Modified is Custom.

To

Conditional

Current date

Sets the end of a custom last-modified range.

Used only when Last Modified is Custom.

In Basic mode, populated filters are combined using AND, and the generated CQL is displayed in the live preview.

CQL mode
image-20261102-075530.png

Field

Required

Default

Description

Notes

CQL

Yes

type = page AND title ~ $$query$$ ORDER BY title

Defines the content returned in the table. Use $$query$$ where reader-entered text should appear.

The statement must be valid Confluence Query Language (CQL). Dynamic page and space variables and complete examples are available beside the editor. If ORDER BY is omitted, the macro adds ORDER BY lastmodified DESC.

Example — count pages changed in the last seven days:

type = page AND lastmodified > now("-7d")

Example — count matching pages in the current space:

type = page AND space = $$space.key$$ AND title ~ $$query$$


Use $$query$$ exactly as shown. The selected Search Mode determines whether fuzzy or wildcard matching is applied, where appropriate.

Supported variables include:

Variable

Replaced with

$$query$$

Text entered in the macro search box, processed using the selected Search Mode

$$space.key$$

Key of the space containing the macro

$$space.title$$

Name of the space containing the macro

$$id$$

ID of the page containing the macro

$$title$$

Title of the page containing the macro

$$created$$

Creation date and time of the page containing the macro

$$lastmodified$$

Last-modified date and time of the page containing the macro

$$parentid$$

ID of the current page's parent


Switching from Basic mode to CQL mode makes the generated query editable.

Switching an advanced CQL query back to Basic mode may not preserve all conditions, so review the parsed fields carefully before saving.


Configure the display

Use the Display tab to configure the count and card appearance.

  1. On the Display tab, configure the display settings.

    image-20261102-080834.png
  2. Add a Default Search Term when the query includes $$query$$. Leave it empty to count everything matched by the remaining query.

Field

Required

Default

Description

Notes

Default Search Term

No

Empty

Sets the value substituted for $$query$$ when the count is loaded.

This is the same value as Search Query in Basic mode. Leave it empty to count everything matched by the remaining query.

Search Mode

No

Contains

Controls how the Default Search Term is matched.

Exact Match uses the text directly; Start With adds ~; Contains adds *. Transformations apply to title ~ $$query$$ and text ~ $$query$$.

Board Size

No

Medium (300 px)

Sets the width and height of the square counter card.

Options are Extra Small (150 px), Small (250 px), Medium (300 px), and Large (400 px).

Content Alignment

No

Center

Aligns the count and footer within the card.

Options are Left, Center, and Right.

Board Color

No

White

Sets the card's background color.

Options are White, Blue, Green, Navy, Yellow, Orange, Purple, and Red.

Footer Text

No

Empty

Adds an optional label below the count.

Accepts up to 100 characters. The card shows the first 16 characters followed by an ellipsis and exposes the complete text in a tooltip.

Show refresh button

No

On

Lets readers update the count without reloading the page.

When enabled, selecting the counter card refreshes it. It also provides Try again after an error.

The card displays up to 16 characters of the footer text, followed by an ellipsis (…) if the text is longer. Hover over the card or footer to view the full text.

Counts above 99,999 are displayed as 99,999+. The exact count remains available in the tooltip and query details.

Using CQL Counter Macro


  • When refresh is enabled, select the card to update the count. A spinner and Updating… status appear while the request is processing.

  • The timestamp below the card shows the time of the last successful update in the viewer’s local timezone.

  • Select View query to view the exact match count and executed CQL. You can also copy the query or open it directly in Confluence search.

  • If the request fails, select Try again to retry. This option is available only when refresh is enabled.


We don't have a way to export this macro.