projectdoc Toolbox

Tips on specifying search queries for Lucene. This also applies to projectdoc's query macros.

projectdoc uses Lucene for searching documents. This document provides some tips on how to formulate queries and extensions to searches provided by projectdoc.

Select Clauses in Display Macros

Select a property by specifying the name of the property.

Select the value of the Name property



Deep Links in Select Clause

Since version 2.0 the projectdoc Toolbox also supports Deep Links as an experimental feature. If the property name references a property whose value is a link, a deep link (specified with "->") allows to traverse the document tree.

Deep Links


Suppose a document provides a property named "Ref" that is a reference to another document.

To select the short description of the referenced document, use Ref->Short Description.

Deep Links may have deeper depth than 1.

Deep Links with Depth > 1



Note that prior to version 2.5 of the projectdoc Toolbox only single valued properties can be used with deep links. So if you are using an older version, if more than one link is found in a property value, only the first will be traversed.

Macros supporting Deep Links:

Display Document Properties Macro
Renders a template with property references.
Display List Macro
Lists references to projectdoc documents in a list. List contain names and optional short descriptions.
Display List Template Macro
Lists references to projectdoc documents in a list. List items are defined by templates referencing properties.
Display Table Macro
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
Index Card Macro
Renders transcluded content fetched from documents of a result set.
Index Entries Table Macro
Renders a table of index entries.
Tour-by-Property Macro
Renders a predefined list of documents in a table . Documents are selected by a document property. Allows to select document properties for columns. Also non-list representations are provided.
Tour Macro
Renders a predefined list of documents in a table.
Transclude Documents Macro
Renders transcluded content fetched from documents of a result set.
Transclusion Macro
Transcludes content from a document marked with the content marker macro.
Transclusion Reference Macro
Transcludes content via a reference from a document marked with the content marker macro.

Where Clauses in Display Macros

The where clause of display macros allows to add a constraint on the documents to display in the result set.

Property Names

To use property names in Lucene searches, the property names must not contain blanks. So if the search is restricted to user stories with just one story point, use this:

StoryPoints = "1" 

Template authors may use the $[...] marker to translate the property name to its normalized form:

$[Story Points] = "1" 

This is especially useful if the labels are provided by localized resource bundles. In this case the template author has not to bother, if the name contains spaces or not.

Reference Property Values

If the result set should contain only documents where one property matches the value of a property of the current document, use the ${...} placeholder to reference the property in the current document.

$[Story Points] = ${Magic Value}

For the example, the result set will only contain documents, that have the Story Point property set to a value matching that of the Magic Value property of the document the search is part of.

Curly Braces


Curly braces may cause problems on some instances of Confluence when used in a string parameter field of a macro. This is especially true (and reproducible) if you use an opening and an immediate closing bracket like this: "{}".

This is a known issue (CONFSERVER-33399) and is also discussed in Do curly braces in string macro parameters break the macro?

To work around this problem you may escape the curly braces with a backslash as in

$[Story Points] = $\{Magic Value\}

You need to use this workaround if you cannot save the page (as described in the issue above). Otherwise it is just a failed rendering of the macro in the macro editor.

Deep Links in Where Clause

Since version 2.0 of the projectdoc Toolbox Deep Links are supported for property references (on the right side) as an experimental features.

$<Story Points> = [${Master->Ref Story Points}]

Note that you cannot use deep links on the left side of the where clause. Read Materialize Properties for more information on this.

Exact Match Queries

If the result should be an exact match query, use the following pattern:

$<Story Points> = [Magic Value]

In case the value is not a constant, you may also use a reference to the property of the document:

$<Story Points> = [${Magic Value}]

The syntax $<...> is read as: Please run the preprocessor of projectdoc over the value before it is passed to Lucene.

Escaping Special Characters

Since version 1.9 it is possible to escape special characters with a backslash (\).

$<Name> = [My Name \(with brackets\)]

To escape the escape character also use the escape character.

$<Name> = [My Name \\ containing a slash]

Subtree Queries

If you need to constrain the search result to documents with a given ancestor, you can take advantage of artificial properties like AncestorNames and AncestorIds.

$<AncestorNames> = [This Root Page]

Or you could constrain the search result by the current page.

$<AncestorIds> = [${Page ID}]

See Subtree Queries for examples.

Ancestor Queries

For some type of properties it is useful to query for a given value or its ancestors. E.g. if you want to have all documents relevant for the Quick Response Team (QRT), a role derived from Ops, you may want to collect all documents marked with either QRT or Ops.

$<Audience> = ^QRT^

This is not only a shortcut for not listening all parents. If you add the following to the role template, the document will show all documents relevant for the role:

$<Audience> = ^${Name}^

Note that in the above example Audience is a property of a document that refers to documents of type Role. The hierarchy is defines on role documents. It may be confusing for new uses if they assume that the hierarchy is defined on the document containing the the Audience property.

If you need to search the hierarchy down the tree, use "°" instead of "^". So "°" stands for downstream, "^" for upstream search.


Ancestor queries are based on the property information in the blueprint of a document type. Document authors cannot define hierarchies based on document instances. It is the job of template authors to do this.

If you encounter unexpected results, you may want to refresh your caches, especially the doctype cache. Please refer to Cache Refresh Actions for details.


See Ancestor Queries for examples.

List Queries



List queries are supported since version 2.0.

List queries run an exact match on a property where one of the values in the list has to match.

$<Name> ~ (One, Two, Three)

expands to

$<Name>=[One] OR $<Name>=[Two] OR $<Name>=[Three]

This is especially useful when a value is provided as a property.

$<Name> ~ (${Some Names})

Note that the List of values found in Some Names may have links or be a macro (such as the Name List Macro). Values with a comma are not allowed since the comma is the delimiter of the list elements.

Useful Examples

Here are some more examples on using queries in various use cases.

Prefix Query

To select all resource documents that are read by a specific user ("jd" in this example) in a given year (specified by the document property Readjd in the format yyyy-MM-dd), use the prefix query:

ReadBy = "jd" AND Readjd = 2014*

Querying List Values

The Tags Property is one that is supported by all document types. It specifies a comma-separated list of values.

To select on those documents by tag values, use this:

Tags = (("test-me" AND "continous-delivery") OR "My-Tag")

Search all Topic Types that are no Fragments

A fragment is a basic document a couple of topic types (table, example, ...) derive from. To select only documents of a type that is not a fragment or one of its subtypes, use the following:

+TypeAncestors:[* TO *] AND -TypeAncestors:Fragment 

Note that in this case all documents have to have their topic type specific. If those that have not should also be part of the result set, use:

+Doctype:topic AND -TypeAncestors:Fragment

Using Dates

Since version 1.10 the projectdoc Toolbox provides normalized date value to be used with Lucene searches. If the property value is specified with the Confluence Date Autocompletion (opened with the shortcut '//'), and for the creation and last modification date, a normalized date is provided as an artificial property.

The name of this artificial property is that of the original property plus the §-sign appended.


Some versions of Confluence do no longer support "NOW" as part of the query string.

We are working on a solution for this issue. See  PDAC-1059 - Getting issue details... STATUS .

Here is an example where the creation date is check against a custom property named Last Update.

$[Creation Date§]: [${Last Update§} TO NOW]

There is also an artificial property value containing the date as a timestamp in milliseconds, prefixed with zeros up to 19 digits (%019d). The name of the artificial property is constructed from the original name plus the suffix Timestamp (separated by a blank). Note that the creation timestamp is called Creation Timestamp (not Creation Date Timestamp).


Appending the $-sign instead of the §-sign will render the text representation of the date.

Using Date Ranges

Confluence provides a couple of search fields to help finding the desired documents.

created:[20150311 TO 20150317]
created:[20150311 TO NOW]

Some versions of Confluence do no longer support "NOW" as part of the query string.

This issue is fixed by supporting search functions since version 3.2 of the projectdoc Toolbox.


Currently (Confluence version 5.7) the more sophisticated searches are only possible via CQL, but not via the Confluence wiki interface (aka search field).

created:[NOW-7DAY TO NOW]
created:[StartOfWeek TO NOW]

See Relative Date Queries with Confluence on Atlassian Answers.

Search Functions

A query function is a virtual function call that will replace the call with the return value of the function.


Search functions are provided since version 3.2 of the projectdoc Toolbox.

The syntax for using search functions is:

$<PROPERTY NAME>=${function-name(argument-list)}

Functions can be used for a value in a Where clause parameter of a projectdoc macro.

Functions cannot be used for a property name or outside the Where clause.


Here are some usage examples:

$<Start Date§>=${now()}

$<Login Name>=${currentUser()}


Supported Functions

The following functions are supported:

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

User Functions

There is only one user function that provides access to the current user of a session.

The currentUser function supports the format argument.

Valid formats are

  • id (default) - login name (id) of the current user
  • fn - Full Name of current user

If no user is currently logged in to the current session, then the format id returns "#anonymous" and the format fn returns "#Anonymous".


The following calls will return the login name of the currently logged in user.


In case the full name, as provided in the user's profile is requested, use:


Date Functions

The date functions provide a date in the format "yyyyMMdd". This way it can easily be compared to date properties by the use of the normalized date representation (add '§' to the name of the property like "Start Date§").

The following functions are provided:



The current date at the time the page is rendered.

startOfDayThe date at the first millisecond on the current day.
endOfDayThe date at the last millisecond on the current day.

The date at the first millisecond of the first day of the week the current day is part of.

Note that currently you cannot control the definition of the first day.


The date at the last millisecond of the last day of the week the current day is part of.

Note that currently you cannot control the definition of the last day.

startOfMonthThe date at the first millisecond of the first day of the month the current day is part of.
endOfMonthThe date at the last millisecond of the first day of the month the current day is part of.
startOfYearThe date at the first millisecond of the first day of the year the current day is part of.
endOfYearThe date at the last millisecond of the first day of the year the current day is part of.

Implementation Details


Note that now is calculated per macro. So in case you have multiple macros on a page, the "now" point in time is when the macro is called. For most use cases this should not make any differences. In case a call is sent some milliseconds before midnight, two macros may calculate different days.

The date functions allow two arguments.

  • format
  • increment 

If you want to specify the increment, but not the format, user "" as the first argument.


Specify the format as defined for the Joda Time date formater: DateTimeFormat.

Typically use:



Year. Typically use "yyyy" for four digits (i.e. 2019).

MMonth. Typically use "MM" for two digits (i.e. 03 and 12).
ddDay. Typically use "dd" for two digits (i.e. 01 and 15).

Hours.  Typically use "HH" for two digits (i.e. 08 and 23).


Minutes.  Typically use "mm" for two digits (i.e. 01 and 59).

The default format is: "yyyyMMdd".


With the second argument to the date function you may alter the date.

The format is:


Use + (default) or - to add or subtract from the calculated value.

Provide the amount of units at 'nn'. If omitted, one is assumed.

Add the unit identifier:








For instance:





Using Checkboxes

You can select property values that are checkbox and use checkboxes in your where clauses.

The checked checkbox has a text value of complete, an unchecked checkbox has a value of incomplete.

See Tasks as Property Values for an example.

Using Not

In general Not in a query is only allowed when it follows an positive expression.

To specify a document property not to have a certain value, use a range query like this:

+ID:[* TO *] AND -ID:6555694

Searching for an empty attribute using Not

Searching all Documents having an attribute that is not set e.g. not having a parent. This is especially useful, if you want to list all root documents of a given document type (see Parent Property of projectdoc Documents for an example using the Parent Property).

*:* -Parent:[* TO *]


*:* NOT Parent:[* TO *]

The *:* is only needed if you have no positive criteria. A Lucene query must not start with "NOT".


If you need to have all documents in the result that that actually have a parent, then use

Parent:[* TO *]

Note that you can only select on properties, not on sections.


If you want to make sure that a document with a specific ID is not part of the result set, use this:

Tags = "logging" NOT ID = 3704077

This does not do the trick (the syntax is wrong):

Tags = "logging" AND ID NOT 3704077

Document Properties for Selection

The Display All Document Properties Macro provides access to the properties and artificial properties a document provides in tabular form.

Mind Stopwords!

Suppose you have two documents with names

  • Querying in apples
  • Querying apples

Here are the query results:

Query StringResultExplanation
Name = "Querying in apples"Only: Querying applesThe stopword 'in' is removed from the query string.
Name = "Querying apples"Only: Querying applesThe document containing the 'in' does not match the given search string.
Name = (Querying in apples)Both: Querying apples and Querying in applesFinds all containing 'Querying' AND 'apples', 'in' is removed since it is a stopword.
Name = (Querying apples)Both: Querying apples and Querying in applesFinds all containing 'Querying' AND 'apples'.
$<Name> = [Querying in apples]Only: Querying in applesAn exact match that checks for the exact phrase.
$<Name> = [Querying apples]Only: Querying applesAn exact match that checks for the exact phrase.


Information on how to create queries to conduct searches.
Confluence Search Syntax
Describes the special words and punctuation marks you can use to refine your search.
Confluence Search Fields
Gives an overview of the Apache Lucene search fields used in Confluence.
Lucene Query Parser Syntax (4.3.0)
Information on the query parser syntax from the API documentation.