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

Introduction

Similar to Canned Search for Confluence Cloud Home , this macro allows you to execute contextual searches with predefined CQL.

Results are displayed in a table with configurable columns.

Configure the query

Insert or edit CQL Search Table Macro.
On the Query tab, build the search in Basic mode or enter CQL directly.

Include $$query$$ if readers should be able to search. For example:

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

Review the live preview.

Query settings reference

CQL mode

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`.

Supported variables are $$query$$, $$space.key$$, $$space.title$$, $$id$$, $$title$$, $$created$$, $$lastmodified$$, and $$parentid$$. Use $$query$$ exactly as shown; Search Mode applies fuzzy or wildcard behavior when appropriate.

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 `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.
Contributors	No	All contributors	Limits results to content associated with selected users.	Multiple users generate one `contributor 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.

Basic mode combines populated filters with AND. Switching from an advanced CQL statement to Basic mode is best-effort, so review every parsed field before saving.

Configure the table

Use the Display tab to configure the search box, result page size, columns, headings, and dates.

Field	Required	Default	Description	Notes
Default Search Term	No	Empty	Runs an initial search with this text when the macro loads.	This is the same value as Search Query in Basic mode. In CQL mode, it replaces `$$query$$`.
Search Variable Placeholder	No	`Search`	Sets the hint displayed in an empty search box.	It does not change the query.
Search Mode	No	Contains	Controls how the search term is matched.	Exact Match uses the text directly; Start With adds `~`; Contains adds `*`. Transformations apply to `title ~ $$query$$` and `text ~ $$query$$`.
Results per page	No	5	Sets the number of rows loaded per result page.	Available values are 5, 10, 50, and 100.
Table Columns	Yes	S/N, Title, Type, Space, Modified	Selects and orders the displayed columns.	Columns appear from left to right in the selected order. At least one column is required.
Column Header Text	Yes	`s/n, title, type, space, modified`	Sets custom comma-separated column headings.	Supply one non-empty heading for each selected column, in the same order.
Date Format	No	`YYYY-MM-DD HH:mm:ss`	Formats Created and Modified values.	Dates are shown in the viewer's local timezone.
Search Bar	No	Visible	Shows or hides the reader-facing search box.	Available only when the active CQL contains `$$query$$`; otherwise the macro runs as a fixed search.
No Results Message	No	`Result not found!`	Sets the message shown when the query returns no rows.	Use a short message that helps readers adjust their search.

Available columns are:

Column	Contents
S/N	Result number across result pages
Title	Linked content title
Space	Linked space name
Type	Content-type icon and name
Created	Creation date in the viewer's local timezone
Modified	Last-modified date in the viewer's local timezone
Creator	Content creator
Modifier	Most recent modifier
Labels	Confluence labels
Version	Current version number
Comments	Comment count
Excerpt	Search-result excerpt with the search term emphasized

At least one valid column and a corresponding non-empty heading are required. If the saved column definition is empty or invalid, the macro falls back to S/N, Title, Type, Space, and Modified.

Date formats

YYYY-MM-DD HH:mm:ss
DD MMM YYYY
MMM DD, YYYY
YYYY-MM-DD
DD MMM YYYY, HH:mm

Use the published table

Select a column heading to sort the rows currently loaded in the table.
Scroll horizontally when the selected columns are wider than the page.
Use the pagination controls to load more results from Confluence.
Select View query to inspect or copy the executed CQL, or open it in Confluence search.

Sorting is applied to the currently loaded result page; use ORDER BY in the CQL when the ordering must be consistent across the complete result set.