CQL fields

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.

Ancestor

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

Syntax

1

ancestor

Field type

CONTENT

Supported operators

Supported functions

None

Examples

• Find all descendant pages with a given ancestor page

  1

  ancestor = 123

• Find descendants of a group of ancestor pages

  1

  ancestor in (123, 456, 789)

Content

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

Syntax

1

content

Field type

CONTENT

Supported operators

Supported functions

None

Examples

• Find content with a given content id

  1

  content = 123

• Find content in a set of content ids

  1

  content in (123, 223, 323)

Created

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

Use one of the following formats:

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

Syntax

1

created

Field type

DATE

Supported operators

Supported functions

• endOfDay()
• endOfMonth()
• endOfWeek()
• endOfYear()
• startOfDay()
• startOfMonth()
• startOfWeek()
• startOfYear()

Examples

• Find content created after the 1st September 2014

  1

  created > 2014/09/01

• Find content created in the last 4 weeks

  1

  created >= now("-4w")

Creator

Search for content that was created by a particular user. You can search by the user's full name (depending on profile visibility), public name or accountId.

Syntax

1

creator

Field type

USER

Supported operators

Supported functions

• currentUser()

Examples

• Find content created by users with a full name (depending on profile visibility) like alana

  1

  creator.fullname ~ "alana"

• Find content created by the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e

  1

  creator = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"

• Find content created by the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e or the user with the accountId 48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01

  1

  creator in ("99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e", "48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01")

Contributor

Search for content that was created or edited by a particular user. You can search by the user's full name (depending on profile visibility), public name or accountId.

Syntax

1

contributor

Field type

USER

Supported operators

Supported functions

• currentUser()

Examples

• Find content created or edited by users with a full name (depending on profile visibility) like alana

  1

  contributor.fullname ~ "alana"

• Find content created or edited by the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e

  1

  contributor = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"

• Find content created or edited by the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e or the user with the accountId 48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01

  1
  2
  3

  ``` bash
  contributor in ("99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e", "48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01")
  ```

favourite, favourite

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

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

Syntax

1

favourite

Field type

USER

Supported operators

Supported functions

• currentUser()

Examples

• Find content that is favorited by the current user

  1

  favourite = currentUser()

• Find content favorited by the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e, where the same user is also the logged-in user

  1
  2
  3

  ``` bash
  favourite = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"
  ```

ID

Search for content that have a given content ID.

Syntax

1

id

Field type

CONTENT

Supported operators

Supported functions

None

Examples

• Find content with the id 123

  1

  id = 123

• Find content in a set of content ids

  1

  id in (123, 223, 323)

Label

Search for content that has a particular label

Syntax

1

label

Field type

STRING

Supported operators

Supported functions

None

Examples

• Find content that has the label finished

  1

  label = finished

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

  1

  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

1

lastmodified

Field type

DATE

Supported operators

Supported functions

• endOfDay()
• endOfMonth()
• endOfWeek()
• endOfYear()
• startOfDay()
• startOfMonth()
• startOfWeek()
• startOfYear()

Examples

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

  1

  lastmodified = 2014-09-01

• Find content that was last modified before the start of the year

  1

  lastmodified < startOfYear()

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

  1

  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

1

macro

Field type

STRING

Supported operators

Supported functions

none

Examples

• Find content that has the Jira issue macro

  1

  macro = jira

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

  1

  macro in (toc, widget)

Mention

Search for content that mentions a particular user. You can search by the user's full name (depending on profile visibility), public name or accountId.

Syntax

1

mention

Field type

USER

Supported operators

Supported functions

• currentUser()

Examples

• Find content that mentions users with a full name (depending on profile visibility) like alana

  1

  mention.fullname ~ "alana"

• Find content that mentions the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e or the user with the accountId 48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01

  1

  mention in ("99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e", "48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01")

• Find content that mentions 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e

  1

  mention = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"

Parent

Search for child content of a particular parent page

Syntax

1

parent

Field type

CONTENT

Supported operators

Supported functions

Examples

• Find child pages of a parent page with ID 123

  1

  parent = 123

Space

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

Syntax

1

space

Field type

SPACE

Supported operators

Supported functions

none

Examples

• Find content in the development space or the QA space

  1

  space in (DEV, QA)

• Find content in the development space

  1

  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.

• Title
• Content body
• Labels

Syntax

1

text

Field type

TEXT

Supported operators

Supported functions

none

Examples

• Find content that contains the word Confluence

  1

  text ~ Confluence

• Find content in the development space

  1

  space = DEV

Title

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

Syntax

1

title

Field type

TEXT

Supported operators

Supported functions

none

Examples

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

  1

  title = "Advanced Searching using CQL"

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

  1

  title ~ "Searching CQL"

Type

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

• page
• blogpost
• comment
• attachment

Syntax

1

type

Field type

TYPE

Supported operators

Supported functions

none

Examples

• Find blogposts or pages

  1

  type IN (blogpost, page)

• Find attachments

  1

  type = attachment

Watcher

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

Syntax

1

watcher

Field type

USER

Supported operators

Supported functions

• currentUser()

Examples

• Search for content that you are watching:

  1

  watcher = currentUser()

• Search for content that the user with the accountId 99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e is watching:

  1

  watcher = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"

User

Search for users visible to you. There are several ways to perform a user search.

Syntax

1

user

Field type

USER

Supported operators

Supported functions

• currentUser()

Examples

• Search for current user:

  1

  user = currentUser()

• Search for users by their full accountId:

  1
  2

  user = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"
  user in ("99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e", "48293:5s04-XXXX-XXXX-XXXX-d7a9b9d8c9f01")

Syntax

1

user.fullname

Field type

USER

Supported operators

Supported functions

None

Examples

• Search for users by their partial full name or public name, whichever is visible:

  1

  user.fullname ~ "John"

Syntax

1

user.accountid

Field type

USER

Supported operators

Supported functions

None

Examples

• Search for users by their accountId:

  1

  user.accountid = "99:27935d01-XXXX-XXXX-XXXX-a9b8d3b2ae2e"