Canned Search for Confluence Cloud

User Guide for CQL Search Table Macro

Introduction


The CQL Search Table macro allows users to search content using predefined CQL queries and display results in a table with configurable columns.

image-20261030-184420.png

Common use cases include searching for titles or keywords within:

  • Meeting minutes for a specific project.

  • Child pages under an SOP page.

  • Training slides and other attachments labelled with training.

Configuration


Configure the query

  1. Insert or edit CQL Search Table Macro.

  2. On the Query tab, choose Basic or CQL.

  3. 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
      
  4. 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
image-20261030-191845.png

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.

In Basic mode, populated filters are combined using AND, and the generated CQL is displayed in the live preview.

CQL mode
image-20261030-190826.png

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.

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

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


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

  1. On the Display tab, configure the display settings

image-20261030-191928.png
    1. Select table columns from the 12 available options in the configuration form: S/N, Title, Space, Type, Created, Modified, Creator, Modifier, Labels, Version, Comments, and Excerpt.

    2. Choose from five date formats for the Created and Modified columns. Dates are displayed in the viewer’s local timezone.

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.

Date formats

  • YYYY-MM-DD HH:mm:ss

  • DD MMM YYYY

  • MMM DD, YYYY

  • YYYY-MM-DD

  • DD MMM YYYY, HH:mm

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 with a non-empty heading is required. If the saved column configuration is empty or invalid, the macro uses the default columns: S/N, Title, Type, Space, and Modified.

Using CQL Search Table Macro


  • 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 applies only to the currently loaded result page. To maintain consistent ordering across the complete result set, use ORDER BY in the CQL.


We don't have a way to export this macro.