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

Introduction

The CQL Search Macro allows users to perform contextual searches using predefined CQL queries and display results in either of two modes:

List Display Mode
Contributor Display Mode

Common use cases include searching for titles or keywords within:

Blog posts about scheduled maintenance.
Meeting minutes for a specific project.
Child pages under an SOP page.
Training slides and other attachments labelled with training.

List Display Mode
Contributor Display Mode

Configuration

Configure the query

Insert or edit CQL Search 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$$
Configure your display mode:
- List: Display search results in a list.
- Contributor: Group or filter search results by contributor.
Check the live preview to confirm that the search returns the expected results.

Query settings reference

CQL mode

Field	Required	Default	Description	Notes
CQL	Yes	`type = page AND title ~ $$query$$`	Defines the content returned by the macro. Use `$$query$$` where reader-entered search text should appear.	Supports dynamic variables such as `$$space.key$$`, `$$id$$`, and `$$parentid$$`. If `ORDER BY` is omitted, results are ordered by `lastmodified DESC`. Reference: How to Search Content effectively with Titles How to limit search to a file type in Confluence Useful scenarios with Canned Search for Confluence Convenient Search with placeholders

Field

Required

Default

Description

Notes

CQL

Yes

type = page AND title ~ $$query$$

Defines the content returned by the macro. Use $$query$$ where reader-entered search text should appear.

Supports dynamic variables such as $$space.key$$, $$id$$, and $$parentid$$. If ORDER BY is omitted, results are ordered by lastmodified DESC.

Reference:

The CQL editor supports the following dynamic variables:

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

Use $$query$$ exactly as shown. Do not add wildcard or fuzzy characters to the variable itself. The selected Search Mode applies the appropriate matching behavior when the query uses title ~ $$query$$ or text ~ $$query$$.

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. Leave it empty to apply only the other filters.
Titles only	No	Off	Searches titles instead of page content.	When enabled, Basic mode generates `title ~ $$query$$`. When disabled, it generates `text ~ $$query$$`.
Spaces	No	All accessible spaces	Limits results to the selected spaces.	Search by space name or key. Multiple spaces are combined in one `space IN (...)` condition.
Contributors	No	All contributors	Limits results to content associated with the selected users.	Search for users by name. Multiple users are combined in one `contributor IN (...)` condition.
Content Type	No	All supported types	Limits results to Pages, Blog posts, Attachments, or Comments.	Multiple types are combined in one `type IN (...)` condition.
Labels	No	Any label	Limits results to content with the selected labels.	One label generates `label = ...`; multiple labels generate `label IN (...)`.
Last Modified	No	Any time	Limits results by the date on which content was last modified.	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.	Displayed and used only when Last Modified is Custom.
To	Conditional	Current date	Sets the end of a custom last-modified range.	Displayed and 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.

Switching 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 control the search box, pagination, result layout, and metadata.

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. It replaces `$$query$$` in CQL mode. Reference: How to use CQL Macro to build a corporate encyclopedia
Search Variable Placeholder	No	`Search`	Sets the hint displayed in an empty search box.	It does not affect the query. It is visible only when the Search Bar is available and enabled.
Search Mode	No	Contains	Controls how the search term is matched.	Exact Match uses the entered text directly. Start With adds the CQL fuzzy suffix (`~`) to each word. Contains adds a trailing wildcard (`*`) to each word. These transformations apply to `title ~ $$query$$` and `text ~ $$query$$`. Reference Support different modes of searching
Results per page	No	5	Sets the number of list results or selected-contributor results shown on each page.	Available values are 5, 10, 50, and 100. Contributor summaries are calculated from the complete result set, independently of this setting. Reference User Guide for CQL Search Macro \| Search Results — with pagination
Display Mode	No	List	Selects the published result presentation.	List shows matching content. Contributor summarizes people associated with the matching content.
Search Bar	No	Visible	Shows or hides the reader-facing search field.	Available only when the active CQL contains `$$query$$`. Without that variable, the macro runs as a fixed search. Reference User Guide for CQL Search Table Macro \| Hidden Search Bar
Show Excerpt	No	Hidden	Shows a search-result excerpt below each item in List mode.	Matching text is emphasized when an excerpt is available.
Show Content Type	No	Visible	Shows the content-type name in result metadata.	Examples include Page, Blog post, Attachment, and Comment.
Show Space	No	Visible	Shows the content's space in result metadata.	The space name links to the space when a link is available.
Show Updated Date/Time	No	Visible	Shows when each result was last updated.	The value is formatted for the viewer.
No Results Message	No	`Result not found!`	Sets the message displayed when the query returns no content.	Use a short message that helps readers adjust their search or filters.

List mode

List mode shows matching content with the configured metadata. Select a title to open the content. Attachment results can include a Download action.
Use View query to inspect the final CQL and total result count. Pagination loads the previous or next result page from Confluence.

Contributor mode

Contributor mode summarizes the people who created or published changes to all matching content.

Select a contributor to show content associated with that person.
Select more contributors to expand the result set.
Use Select all to show content associated with every listed contributor.
Use Clear selection to return to the contributor summary.

The macro loads all matching pages before it finalizes the summary, so a broad query can take longer than List mode. Progress appears while results are loading. Searches above 15,000 results are stopped for safety; add a condition such as created >= "2026-01-01" or lastmodified >= "2026-01-01" and try again.

Example configurations

Pages in the current space with reader-entered title text:

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

Recently changed content by contributor:

type = page AND lastmodified > now("-30d") ORDER BY lastmodified DESC

For the second example, use Contributor display mode and leave the search bar hidden because the query does not need reader input.