CQL 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
• Container
• Content
• Created
• Creator
• Contributor
• Favourite, favorite
• ID
• Label
• Last modified
• Macro
• Mention
• Parent
• Space
  • Space category
  • Space key
  • Space title
  • Space type
• Text
• Title
• Type
• Watcher

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)

Container

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

Syntax

1

container

Field Type

CONTENT

Supported Operators

Supported Functions

None

Examples

• Find attachments contained in a page with the given content ID.

  1

  container = 123 and type = attachment

• Find content container in a set of pages with the given IDs.

  1

  container in (123, 223, 323)

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).

Note: search results will be relative to your configured time zone (which is by default the Confluence server 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

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 username.

Syntax

1

creator

Field Type

USER

Supported Operators

Supported Functions

• currentUser()

Examples

• Find content created by jsmith.

  1

  created = jsmith

• Find content created by john smith or bob nguyen.

  1

  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

1

contributor

Field Type

USER

Supported Operators

Supported Functions

• currentUser()

Examples

• Find content created by jsmith.

  1

  contributor = jsmith

• Find content created by john smith or bob nguyen.

  1

  contributor in (jsmith, bnguyen)

Favourite, favorite

Search for content that was favorited 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

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 jsmith, where jsmith is also the logged in user.

  1

  favourite = jsmith

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)

Last modified

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 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 username.

Syntax

1

mention

Field Type

USER

Supported Operators

Supported Functions

• currentUser()

Examples

• Find content that mentions jsmith or kjones.

  1

  mention in (jsmith, kjones)

• Find content that mentions jsmith.

  1

  mention = jsmith

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. By default, this searches by space key. You can also search by category, title, and type (see below).

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

Space category

Search for spaces with a particular space category applied. Categories are used to organise spaces in the space directory. Available from Confluence 6.15 and later.

Syntax

1

space.category

Field Type

STRING

Supported Operators

Supported Functions

None

Examples

• Find spaces that have the category 'development'

  1

  space.category = development

• Find spaces that don't have the category 'marketing' or 'operations'

  1

  space.category not in (marketing, operations)

Space key

Search for spaces by space key.

Syntax

1

space.key

Field Type

STRING

Supported Operators

Supported Functions

None

Examples

• Find the space that has the key 'DEV'

  1

  space.key = DEV

• Find spaces that have either 'MKT' or 'OPS' or 'DEV'

  1

  space.key in (MKT, OPS, DEV)

Space title

Search for spaces by title.

Syntax

1

space.title

Field Type

TEXT

Supported Operators

Supported Functions

None

Examples

• Find spaces with titles that match 'Development Team' (fuzzy match)

  1

  space.title ~ "Development Team"

• Find spaces with titles that don't match "Project" (fuzzy match)

  1

  space.title !~ "Project"

Space type

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

• personal
• global (also known as site spaces)
• favourite, favorite (also known as My Spaces)

Syntax

1

space.type

Field Type

TYPE

Supported Operators

Supported Functions

None

Examples

• Find only personal spaces

  1

  space.type = personal

• Find only site / global spaces

  1

  space.type = global

• Find only site / favorite spaces

  1

  space.type = favorite

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

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

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.

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

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 username.

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 "jsmith" is watching.

  1

  watcher = "jsmith"