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.
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$$
-
-
Check the live preview to confirm that the search returns the expected results.
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. Leave it empty to apply only the other filters. |
|
Titles only |
No |
Off |
Searches titles instead of page content. |
When enabled, Basic mode generates |
|
Spaces |
No |
All accessible spaces |
Limits results to the selected spaces. |
Search by space name or key. Multiple spaces are combined in one |
|
Contributors |
No |
All contributors |
Limits results to content associated with the selected users. |
Search for users by name. Multiple users are combined in one |
|
Content Type |
No |
All supported types |
Limits results to Pages, Blog posts, Attachments, or Comments. |
Multiple types are combined in one |
|
Labels |
No |
Any label |
Limits results to content with the selected labels. |
One label generates |
|
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.
CQL mode
|
Field |
Required |
Default |
Description |
Notes |
|---|---|---|---|---|
|
CQL |
Yes |
|
Defines the content returned by the macro. Use |
Supports dynamic variables such as Reference: |
Use $$query$$ exactly as shown. The selected Search Mode determines the matching behaviour when using title ~ $$query$$ or text ~ $$query$$, applying fuzzy or wildcard matching as 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 from CQL mode 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.
-
On the Display tab, configure the display settings
-
Choose your display mode
-
List: Display search results in a list.
-
Contributor: Group or filter search results by contributor.
-
-
Choose which details to display in search results, including excerpts, content type, space, and last-updated date and time.
-
|
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 Reference: |
|
Search Variable Placeholder |
No |
|
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 ( Reference |
|
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 |
|
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 Reference |
|
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 |
|
Sets the message displayed when the query returns no content. |
Use a short message that helps readers adjust their search or filters. |
Display settings reference
List mode
Contributor mode
Using CQL Search Macro
List Mode
-
View clearer content-type labels and icons in search results.
-
Select View Query / Hide Query to show or hide the executed CQL and search term.
-
View the total number of matches directly in the published macro.
-
Select a result title to open the content.
-
Attachment results may also include a Download action.
-
Use pagination to navigate between previous and next result pages.
Contributor mode
Contributor mode summarises the people who created or last modified the matching content.
-
Select a contributor to view content associated with that person.
-
Select multiple contributors to expand the results.
-
Use Select all to view content associated with all listed contributors.
-
Use Clear selection to return to the contributor summary.
-
The macro loads all matching content before generating the contributor summary. Broad searches may take longer than List mode. A progress indicator is displayed while results are loading.
-
Searches exceeding 15,000 results are stopped to prevent excessive processing. To narrow your search, add a date condition such as
created >= "2026-01-01"orlastmodified >= "2026-01-01", then try again.
Examples
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.