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

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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)

^top of fields | ^^top of topic

Container

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

Syntax
container
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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)

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)


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)

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(tick)

(tick)

(tick)

(tick)

(error)

(error)

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

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

Supported Functions

Examples
  • Find content created by jsmith

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

    created in (jsmith, bnguyen)

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

Supported Functions

Examples
  • Find content created by jsmith

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

    contributor in (jsmith, bnguyen)

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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

^top of fields | ^^top of topic

ID

Search for content that have a given content ID.

Syntax
id
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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)

^top of fields | ^^top of topic

Label

Search for content that has a particular label

Syntax
label
Field Type

STRING

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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)

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(tick)

(tick)

(tick)

(tick)

(error)

(error)

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"

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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)

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

Supported Functions

Examples
  • Find content that mentions jsmith or kjones

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

    mention = jsmith

^top of fields | ^^top of topic

Parent

Search for child content of a particular parent page

Syntax
parent
Field Type

CONTENT

Supported Operators

=

!=

~

!~

>

>=

<

<=

IN

NOT IN

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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

    parent = 123

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

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

^top of fields | ^^top of topic

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

(error)

(error)

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

Supported Functions

none

Examples
  • Find content that contains the word Confluence

    text ~ Confluence
  • Find content in the development space

    space = DEV

^top of fields | ^^top of topic

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

(tick)

(tick)

(tick)

(tick)

(error)

(error)

(error)

(error)

(tick)

(tick)

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"

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

Supported Functions

none

Examples
  • Find blogposts or pages

    type IN (blogpost, page)
  • Find attachments

    type = attachment

^top of fields | ^^top of topic

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

(tick)

(tick)

(error)

(error)

(error)

(error)

(error)

(error)

(tick)

(tick)

Supported Functions

Examples
  • Search for content that you are watching:

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

    watcher = "jsmith"

^top of fields | ^^top of topic

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport