Advanced Searching using CQL

The instructions on this page describe how to define and execute a search using the advanced search capabilities of the Confluence REST API. 

What is an advanced search?

An advanced search allows you to use structured queries to search for content in Confluence. Your search results will take the same form as the Content model returned by the Content REST API.

When you perform an advanced search, you are using the Confluence Query Language (CQL).

A simple query in CQL (also known as a 'clause') consists of a field, followed by an operator, followed by one or more values or functions. For example, the following simple query will find all content in the "TEST" space. It uses uses the Space field, the EQUALS operator, and the value "TEST".)

space = "TEST"

It is not possible to compare two fields.

NOTE: CQL gives you some SQL-like syntax, such as the ORDER BY SQL keyword. However, CQL is not a database query language. For example, CQL does not have a SELECT statement.

 

 

Related topics:

 

How to perform an advanced search

The Content API REST Resource now supports CQL as a query parameter to filter the list of returned content.

http://myhost:8080/rest/api/content/search?cql=space=TEST

To perform an advanced search:

  1. Add your query using the fieldsoperators and field values or functions as the value for the CQL query parameter.
  2. Execute a GET request on the resource, you can apply expansions and pagination as you would normally in the Confluence REST API.

Performing text searches

You can use the CONTAINS operator to use Lucene's text-searching features when performing searches on these fields:

  • title
  • text
  • space.title

For details, please see the page on Performing text searches.

Setting precedence of operators

You can use parentheses in complex CQL statements to enforce the precedence of operators.

For example, if you want to find all pages in the Developer space as well as all blog posts created by the the system administrator (bobsmith), you can use parentheses to enforce the precedence of the boolean operators in your query. For example:

(type=page and Space=DEV) OR (creator=bobsmith and type=blogpost)

Note: if you do not use parentheses, the statement will be evaluated left to right.

You can also use parentheses to group clauses, so that you can apply the NOT operator to the group.

Keyword reference

A keyword in CQL is a word or phrase that:
  • joins two or more clauses together to form a complex CQL query, or
  • alters the logic of one or more clauses, or
  • alters the logic of operators, or
  • has an explicit definition in a CQL query, or
  • performs a specific function that alters the results of a CQL query.

List of Keywords:

AND

Used to combine multiple clauses, allowing you to refine your search.

Note: you can use parentheses to control the order in which clauses are executed.

Examples
  • Find all blogposts with the label "performance"

    label = "performance" and type = "blogpost"
  • Find all pages created by jsmith in the DEV space

    type = page and creator = jsmith and space = DEV
  • Find all content that mentions jsmith but was not created by jsmith

    mention = jsmith and creator != jsmith

OR

Used to combine multiple clauses, allowing you to expand your search.

Note: you can use parentheses to control the order in which clauses are executed.

(Note: also see IN, which can be a more convenient way to search for multiple values of a field.)

Examples
  • Find all content in the IDEAS space or with the label idea

    space = IDEAS or label = idea
  • Find all content last modified before the start of the year or with the label needs_review

    lastModified < startOfYear() or label = needs_review

NOT

Used to negate individual clauses or a complex CQL query (a query made up of more than one clause) using parentheses, allowing you to refine your search.

(Note: also see NOT EQUALS ("!="), DOES NOT CONTAIN ("!~") and NOT IN.)

Examples
  • Find all pages with the "cql" label that aren't in the dev space

    label = cql and not space = dev 

ORDER BY

Used to specify the fields by whose values the search results will be sorted.

By default, the field's own sorting order will be used. You can override this by specifying ascending order ("asc") or descending order ("desc").

Not all fields support Ordering. Generally, ordering is not supported where a piece of content can have multiple values for a field, for instance ordering is not supported on labels.

Examples
  • Find content in the DEV space ordered by creation date

    space = DEV order by created
  • Find content in the DEV space ordered by creation date with the newest first, then title

    space = DEV order by created desc, title
  • Find pages created by jsmith ordered by space, then title

    creator = jsmith order by space, title asc

Operator reference

  An operator in CQL is one or more symbols or words which compares the value of a field on its left with one or more values (or functions) on its right, such that only true results are retrieved by the clause. Some operators may use the NOT keyword.

List of Operators:

EQUALS: =

The "=" operator is used to search for content where the value of the specified field exactly matches the specified value. (Note: cannot be used with text fields; see the CONTAINS operator instead.)

To find content where the value of a specified field exactly matches multiple values, use multiple "=" statements with the AND operator.

Examples
  • Find all content that were created by jsmith:

    creator = jsmith
  • Find all content that has the title "Advanced Searching"

    title = "Advanced Searching"

NOT EQUALS: !=

The "!=" operator is used to search for content where the value of the specified field does not match the specified value. (Note: cannot be used with text fields; see the DOES NOT MATCH ("!~") operator instead.)

Note: typing field != value is the same as typing NOT field = value.

Currently a negative expression cannot be the first clause in a CQL statement

Examples
  • Find all content in the DEV space that was created by someone other than jsmith:

    space = DEV and not creator = jsmith

    or:

    space = DEV and creator != jsmith
  • Find all content that was created by me but doesn't mention me

    creator = currentUser() and mention != currentUser()

GREATER THAN: >

The ">" operator is used to search for content where the value of the specified field is greater than the specified value. Cannot be used with text fields.

Note that the ">" operator can only be used with fields which support range operators (e.g. date fields and numeric fields). To see a field's supported operators, check the individual field reference.

Examples
  • Find all content created in the last 4 weeks

    created > now("-4w")
  • Find all attachments last modified since the start of the month

    created > startOfMonth() and type = attachment

 

GREATER THAN EQUALS: >=

The ">=" operator is used to search for content where the value of the specified field is greater than or equal to the specified value. Cannot be used with text fields.

Note that the ">=" operator can only be used with fields which support range operators (e.g. date fields). To see a field's supported operators, check the individual field reference.

Examples
  • Find all content created on or after 31/12/2008:

    created >= "2008/12/31"

 

LESS THAN: <

The "<" operator is used to search for content where the value of the specified field is less than the specified value. Cannot be used with text fields.

Note that the "<" operator can only be used with fields which support range operators (e.g. date fields). To see a field's supported operators, check the individual field reference.

Examples
  • Find all pages lastModified before the start of the year

    lastModified < startOfYear() and type = page

 

LESS THAN EQUALS: <=

The "<=" operator is used to search for content where the value of the specified field is less than or equal to than the specified value. Cannot be used with text fields.

Note that the "<=" operator can only be used with fields which support range operators (e.g. date fields). To see a field's supported operators, check the individual field reference.

Examples
  • Find blogposts created in the since the start of the fortnight

    created >= startOfWeek("-1w") and type = blogpost

 

IN

The "IN" operator is used to search for content where the value of the specified field is one of multiple specified values. The values are specified as a comma-delimited list, surrounded by parentheses.

Using "IN" is equivalent to using multiple EQUALS (=) statements with the OR keyword, but is shorter and more convenient. That is, typing creator IN (tom, jane, harry) is the same as typing creator = "tom" OR creator = "jane" OR creator = "harry".

Examples
  • Find all content that mentions either jsmith or jbrown or jjones:

    mention in (jsmith,jbrown,jjones)
  • Find all content where the creator or contributor is either Jack or Jill:

    creator in (Jack,Jill) or contributor in (Jack,Jill)

 

NOT IN

The "NOT IN" operator is used to search for content where the value of the specified field is not one of multiple specified values.

Using "NOT IN" is equivalent to using multiple NOT_EQUALS (!=) statements, but is shorter and more convenient. That is, typing creator NOT IN (tom, jane, harry) is the same as typing creator != "tom" AND creator != "jane" AND creator != "harry".

Examples
  • Find all content where the creator is someone other than Jack, Jill or John:

    space = DEV and creator not in (Jack,Jill,John)

 

CONTAINS: ~

The "~" operator is used to search for content where the value of the specified field matches the specified value (either an exact match or a "fuzzy" match — see examples below). The "~" operator can only be used with text fields, for example:

  • title
  • text

Note: when using the "~" operator, the value on the right-hand side of the operator can be specified using Confluence text-search syntax.

Examples
  • Find all content where the title contains the word "win" (or simple derivatives of that word, such as "wins"):

    title ~ win
  • Find all content where the title contains a wild-card match for the word "win":

    title ~ "win*"
  • Find all content where the text contains the word "advanced" and the word "search":

    text ~ "advanced search"

 

DOES NOT CONTAIN: !~

The "!~" operator is used to search for content where the value of the specified field is not a "fuzzy" match for the specified value. The "!~" operator can only be used with text fields, for example:

  • title
  • text

Note: when using the "!~" operator, the value on the right-hand side of the operator can be specified using Confluence text-search syntax.

Examples
  • Find all content where the title does not contain the word "run" (or derivatives of that word, such as "running" or "ran"):

    space = DEV and title !~ run

 

Field reference

A field in CQL is a word that represents an indexed property of content in Confluence. In a clause, a field is followed by an operator, which in turn is followed by one or more values (or functions). The operator compares the value of the field with one or more values or functions on the right, such that only true results are retrieved by the clause.

List of Fields:

Ancestor

Search for all pages that are descendants of a given ancestor page. This includes direct child pages and their descendents. It is more general than the parent field.

Syntax
ancestor
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

None

Examples
  • Find all descendent pages with a given anscestor page

    ancestor = 123
  • Find descendants of a group of ancestor pages

    ancestor in (123, 456, 789)

Container

Search for content that is contained in the content with the given ID

Syntax
container
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

None

Examples
  • Find attachments contained in a page with the given content id

    container = 123 and type = attachment
  • Find content container in a set of pages with the given ids

    container in (123, 223, 323)

Content

Search for content that have a given content ID. This is an alias of the ID field.

Syntax
content
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes


Supported Functions
None
Examples
  • Find content with a given content id

    content = 123
  • Find content in a set of content ids

    content in (123, 223, 323)

 

Created

Search for content that was created on, before or after a particular date (or date range).

Note: search results will be relative to your configured time zone (which is by default the Confluence server's time zone)

Use one of the following formats:

"yyyy/MM/dd HH:mm"
"yyyy-MM-dd HH:mm"
"yyyy/MM/dd"
"yyyy-MM-dd"

Syntax
created
Field Type

DATE

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

Yes

Yes

Yes

Yes

No

No

Supported Functions

Examples
  • Find content created after the 1st September 2014

    created > 2014/09/01
  • Find content created in the last 4 weeks

    created >= now("-4w")

 

Creator

Search for content that was created by a particular user. You can search by the user's username.

Syntax
creator
Field Type

USER

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

Examples
  • Find content created by jsmith

    created = jsmith
  • Find content created by john smith or bob nguyen

    created in (jsmith, bnguyen)

 

Contributor

Search for content that was created or edited by a particular user. You can search by the user's username.

Syntax
contributor
Field Type

USER

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

Examples
  • Find content created by jsmith

    contributor = jsmith
  • Find content created by john smith or bob nguyen

    contributor in (jsmith, bnguyen)

 

Favourite, favorite

Search for content that was favourited by a particular user. You can search by the user's username.

Due to security restrictions you are only allowed to filter on the logged in user's favourites. This field is available in both British and American spellings.

Syntax
favourite
Field Type

USER

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

Examples
  • Find content that is favourited by the current user

    favourite = currentUser()
  • Find content favourited by jsmith, where jsmith is also the logged in user

    favourite = jsmith

 

ID

Search for content that have a given content ID.

Syntax
id
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

None

Examples
  • Find content with the id 123

    id = 123
  • Find content in a set of content ids

    id in (123, 223, 323)

Label

Search for content that has a particular label

Syntax
label
Field Type

STRING

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

None

Examples
  • Find content that has the label finished

    label = finished
  • Find content that doesn't have the label draft or review

    label not in (draft, review)

 

LastModified

Search for content that was last modified on, before, or after a particular date (or date range).

The search results will be relative to your configured time zone (which is by default the Confluence server's time zone)

Use one of the following formats:

"yyyy/MM/dd HH:mm"
"yyyy-MM-dd HH:mm"
"yyyy/MM/dd"
"yyyy-MM-dd"

Syntax
lastmodified
Field Type

DATE

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

Yes

Yes

Yes

Yes

No

No

Supported Functions

Examples
  • Find content that was last modified on 1st September 2014

    lastmodified = 2014-09-01
  • Find content that was last modified before the start of the year

    lastmodified < startOfYear()
  • Find content that was last modified on or after 1st September but before 9am on 3rd September 2014

    lastmodified >= 2014-09-01 and lastmodified < "2014-09-03 09:00"

 

Macro

Search for content that has an instance of the macro with the given name in the body of the content

Syntax
macro
Field Type

STRING

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

none

Examples
  • Find content that has the JIRA issue macro

    macro = jira
  • Find content that has Table of content macro or the widget macro

    macro in (toc, widget)

 

Mention

Search for content that mentions a particular user. You can search by the user's username.

Syntax
mention
Field Type

USER

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

Examples
  • Find content that mentions jsmith or kjones

    mention in (jsmith, kjones)
  • Find content that mentions jsmith

    mention = jsmith

 

Parent

Search for child content of a particular parent page

Syntax
parent
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions
Examples
  • Find child pages of a parent page with ID 123

    parent = 123

 

Space

Search for content that is in a particular Space. You can search by the space's key.

Syntax
space
Field Type

SPACE

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

none

Examples
  • Find content in the development space or the QA space

    space in (DEV, QA)
  • Find content in the development space

    space = DEV

 

Text

This is a "master-field" that allows you to search for text across a number of other text fields. These are the same fields used by Confluence's search user interface.

Note: Confluence text-search syntax can be used with this field.

Syntax
text
Field Type

TEXT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

No

No

Yes

Yes

No

No

No

No

No

No

Supported Functions

none

Examples
  • Find content that contains the word Confluence

    text ~ Confluence
  • Find content in the development space

    space = DEV

 

Title

Search for content by title, or with a title that contains particular text.

Note: Confluence text-search syntax can be used with this fields when used with the CONTAINS operator ("~", "!~")

Syntax
title
Field Type

TEXT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

Yes

Yes

No

No

No

No

Yes

Yes

Supported Functions

none

Examples
  • Find content with the title "Advanced Searching using CQL"

    title = "Advanced Searching using CQL"
  • Find content that matches Searching CQL (i.e. a "fuzzy" match):

    title ~ "Searching CQL"

 

Type

Search for content of a particular type. Supported content types are:

  • page
  • blogpost
  • comment
  • attachment
Syntax
type
Field Type

TYPE

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

none

Examples
  • Find blogposts or pages

    type IN (blogpost, page)
  • Find attachments

    type = attachment

 

Watcher

Search for content that a particular user is watching. You can search by the user's username.

Syntax
watcher
Field Type

USER

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

Yes

Yes

No

No

No

No

No

No

Yes

Yes

Supported Functions

Examples
  • Search for content that you are watching:

    watcher = currentUser()
  • Search for content that the user "jsmith" is watching:

    watcher = "jsmith"

 

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport