User Guide for CQL Counter Macro | Canned Search for Confluence Cloud

Introduction

The CQL Counter Macro displays the number of search result for a predefined CQL. It has the following features:

Display the value in large font with optional footer text
Background colour and the size can be changed
Support Convenient Search with placeholders in the CQL query

Configure the count

Insert or edit CQL Counter Macro.
On the Query tab, use Basic mode or enter CQL directly.
Add a Default Search Term when the query includes $$query$$. Leave it empty to count everything matched by the remaining query.
Select the search mode used to process the default term.
Confirm the result in the live preview.

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$$

Query settings reference

CQL mode

Field	Required	Default	Description	Notes
CQL	Yes	`type = page AND title ~ $$query$$ ORDER BY title`	Defines the content counted by the macro. Use `$$query$$` where the Default Search Term should appear.	The statement must be valid Confluence Query Language (CQL). Dynamic variables and complete examples are available beside the editor. If `ORDER BY` is omitted, the macro adds `ORDER BY lastmodified DESC`.

Supported variables are $$query$$, $$space.key$$, $$space.title$$, $$id$$, $$title$$, $$created$$, $$lastmodified$$, and $$parentid$$.

Basic mode

Field	Required	Default	Description	Notes
Search Query	No	Empty	Sets the term substituted for `$$query$$`.	This is the same value as Default Search Term on the Display tab. Leave it empty to count content matched by the other filters.
Titles only	No	Off	Matches the term against titles instead of content.	Generates `title ~ $$query$$` when enabled and `text ~ $$query$$` when disabled.
Spaces	No	All accessible spaces	Limits the count to selected spaces.	Search by space name or key. Multiple spaces generate one `space IN (...)` condition.
Contributors	No	All contributors	Limits the count to content associated with selected users.	Multiple users generate one `contributor IN (...)` condition.
Content Type	No	All supported types	Limits the count to Pages, Blog posts, Attachments, or Comments.	Multiple types generate one `type IN (...)` condition.
Labels	No	Any label	Limits the count to content with selected labels.	One label generates `label = ...`; multiple labels generate `label IN (...)`.
Last Modified	No	Any time	Limits the count by 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.

Basic mode combines populated filters with AND. Switching from advanced CQL back to Basic mode is best-effort; review every parsed field before saving.

Configure the card

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

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 footer characters followed by an ellipsis; hover over the card or footer to see the full text. Counts above 99,999 appear as 99999+, while the exact value remains available in the tooltip and query details.

Use the published counter

When refresh is enabled, select the card to update it. A spinner and Updating… status appear during the request.
The timestamp below the card shows the last successful update in the viewer's local time.
Select View query to see the exact match count and executed CQL, copy it, or open it in Confluence search.
If the request fails, use Try again when refresh is enabled.