Introduction
The CQL Counter Macro displays the number of search results returned by a predefined CQL query.
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
-
Insert or edit CQL Counter Macro.
-
On the Query tab, choose Basic or CQL.
-
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
-
-
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
|
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 |
|
Spaces |
No |
All accessible spaces |
Limits results to selected spaces. |
Search by space name or key. Multiple spaces generate one |
|
Content Type |
No |
All supported types |
Limits results to Pages, Blog posts, Attachments, or Comments. |
Multiple types generate one |
|
Labels |
No |
Any label |
Limits results to content with selected labels. |
One label generates |
|
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
|
Field |
Required |
Default |
Description |
Notes |
|---|---|---|---|---|
|
CQL |
Yes |
|
Defines the content returned in the table. Use |
The statement must be valid Confluence Query Language (CQL). Dynamic page and space variables and complete examples are available beside the editor. If |
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 |
|---|---|
|
|
Text entered in the macro search box, processed using the selected Search Mode |
|
|
Key of the space containing the macro |
|
|
Name of the space containing the macro |
|
|
ID of the page containing the macro |
|
|
Title of the page containing the macro |
|
|
Creation date and time of the page containing the macro |
|
|
Last-modified date and time of the page containing the macro |
|
|
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.
-
On the Display tab, configure the display settings.
-
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 |
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 |
|
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.