_CQL
Confluence search filters are powered by CQL.
What's CQL and how do I use it?
CQL (Confluence Query Language) is a query language developed for Confluence, which you can use in some macros and the Confluence search. Confluence search and CQL-powered macros allow you to add filters to build up a search query, adding as many filters as you need to narrow down the search results. To add a filter to your query, select the Add a filter link.
You can use the following CQL filters:
| Filter | Description | Operators |
|---|---|---|
Label* | Returns pages, blog posts or attachments with these labels. | OR (multiple values in the same filter) AND (multiple Label filters) |
| With ancestor | Returns pages that live under this page in the page tree. This allows you to restrict the macro to a single page tree. | OR (multiple values in the same filter) |
| Contributor** | Returns pages or blog posts that were created or edited by these people. | OR (multiple values in the same filter) |
| Creator | Returns items created by these people. | OR (multiple values in the same filter) |
Mentioning user | Returns pages and blog posts that @mention these people. | OR (multiple values in the same filter) |
| With parent | Returns only direct children of this page (further sub-pages won't be included) | EQUALS (one page only) |
| In space** | Returns items from these spaces. | OR (multiple values in the same filter) |
| Including text** | Returns items that contain this text. | CONTAINS (single word or phrase) |
| With title | Returns items that contain this text in the title. | CONTAINS (single word or phrase) |
| Of type** | Returns only pages, blogs or attachments. | OR (multiple values in the same filter) |
AND, OR, and NOT operators
- For an OR search, specify multiple values in the same field.
So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label field, like this:
- For an AND search, add more than one filter and specify a single value in each.
To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second Label field to the macro, and put 'label-b' in the second one, like this:
Put simply, OR values are entered in the same filter, AND values are entered in different filter.
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to add that filter more than once. - For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.
* This field is required in CQL-powered macros.
** You can add these filters in CQL-powered macros but in search they're part of the standard search filters, so they don't appear in the Add a filter menu.