Search Tips

Document Properties Marker

overridedoctype	false

Doctype

topic

hide

Name

override	false

Short Description

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

Name

Search Tips

Parent

Parent Property

property-name	Name

Audience

Name List

doctype	role

render-no-hits-as-blank	true
render-list-as-comma-separated-values	true
names	Author, Documentation Architect

, Documentation Gardener, Template Author


property	Audience

Level of Experience

Name List

doctype	experience-level
render-no-hits-as-blank	true
property	Level of Experience

Expected Duration

Tags

Tag List

names	Search

Iteration


value	finishedproduction

hide

Type

Name List

doctype	topic-type
render-no-hits-as-blank	true
names	Reference
property	Type

Sort Key

hide

sectionprojectdoc-section

Section

show-title	false
title	Description

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

projectdoc-

title	Prerequisites

box-caution

title

Abstract

Use Exact Match Queries

Searches with Lucene are by design lenient. In case your are looking for a term, Lucene is capable of applying grammar rules to not run exact match searches. While this is great for the typical full text search, in case you are matching with properties you may want to be strict. For these use cases the projectdoc Toolbox provides the Exact Match Query.

Exact Match Queries are the recommended way of specifying queries.

Section

title	Prerequisites

Section

title	Abstract

Section

title	Select Clauses in Display Macros

Select a property by specifying the name of the property.

Example Box

title	Select the

Section

title	Select Clauses in Display Macros

Select a property by specifying the name of the property.

Example Box

title	Select the value of the Name property

Name

.

Macros supporting Deep Links:

Display Table Macro

Transclude Documents Macro

Display List Macro

Display List Template Macro

Tour Macro

Macros supporting Deep Links:

Section

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

Example Box

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

Example Box

title	Deep Links with Depth > 1

Ref->Person->Address->Phone

Note that currently prior to version 2.5 of the projectdoc Toolbox only single valued properties can be used with deep links. If 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. See

Jira

server	smartics JIRA
serverId	79ad43bc-d289-364e-bfc7-46c09847bebd
key	PDAC-825

Display Table

doctype	macro
render-mode	definition
select	Name, Short Description
space-keys	PDAC1
where	$<Tags>=[Deep Link]

Display Document Properties Macro

Section

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

section

Section

title	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:

Code Block

language	text

StoryPoints = "1"

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

Code Block

language	text

$[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.

projectdoc-

box-note

title

Reference Property Values

Exact Match Queries recommended

We would recommend to run Exact Match Queries per default on property values.

The example above does not use it so that we do not explain two concepts here.

Section

title	Reference Property Values

If the result set should contain only documents where one property 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.

Code Block

language	text

$[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.

projectdoc-transclusion-macro

document	@self
ids	Exact Match Queries recommended

projectdoc-content-marker

id	curly-braces

Caution Box

title	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

Code Block

language	text

$[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.

Section

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

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

This issue is solved since version 5.0.

projectdoc-projectdoc-section

title	Exact Match Queries

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

Code Block

language	text

$<Story Points> = [Magic Value]

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

Code Block

language	text

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

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

Section

title	Escaping Special Characters

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

Code Block

language	text

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

To escape the escape character also use the escape character.

Code Block

language	text

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

See Subtree Queries for examples

.

Section

title	Subtree Queries	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.

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

Note that you cannot use deep links on the left side of the where clause without Materialization. Since version 4.5 this is supported by property control mat, by space property Materialize by Doctype, or by Doctype Descriptor. Materialization is also possible in prior versions of the projectdoc Toolbox with a little more verbose approach. Read Materialize Properties for more information on this

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.

Code Block

language	text

$<AncestorNames> = [This Root Page]

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

Code Block

language	text

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

Tip Box

Section

title	Ancestor Subtree 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 OpsIf you need to constrain the search result to documents with a given ancestor, you can take advantage of artificial properties like AncestorNames and AncestorIds.

Code Block

language	text

$<Audience>$<AncestorNames> = ^QRT^[This Root Page]

Or you could constrain the search result by the current page.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:

Code Block

language	text

$<Audience>$<AncestorIds> = ^${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.

Caution Box

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.

Tip Box
See Ancestor Queries for examples.

[${Page ID}]

Tip Box
See Subtree Queries for examples.

Section

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

Code Block

language	text

$<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:

Code Block

language	text

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

Caution Box

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.

Tip Box
See Ancestor Queries for examples.

projectdoc-projectdoc-section

title	List Queries

Version Box

title	2.0

List queries are supported since version 2.0.

Content Marker

id	List Query Examples

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

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

expands to

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

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

Code Block
$<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.

Section

title	Useful Examples

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

Prefix Query

Section

title	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:

Code Block

language	text

ReadBy = "jd" AND Readjd = 2014*

Section

title	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:

Code Block

language	text

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

Section

title	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:

Code Block

language	text

+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:

Code Block

language	text

+Doctype:topic AND -TypeAncestors:Fragment

Section

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

Image Modified

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

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

Code Block

language	text

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

Date Timestamp).

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

Section

title	Using Date Ranges

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

Code Block

language	text

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

Ranges work with Date Functions. Use the normalized date value to define range boundaries.

Code Block

language	text

Date§: [20190101 TO ${now("", "-6w")}]
Date§: [${now("", "-6w")} TO ${now("", "-4w")}]

The Date property is recommended to be specified with the Confluence Date Autocompletion (opened with the shortcut '//').

Section

title	Search Functions

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

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

The syntax for using search functions is:

Code Block

language	text

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

Example Box

Here are some usage examples:

Code Block

language	text

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

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

$<Attendee>=${currentUser("fn")}

Section

title	Supported Functions

The following functions are supported:

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

Section

title	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".

Example Box

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

Code Block

language	text

currentUser()
currentUser("")
currentUser("id")

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

Code Block

language	text

currentUser("fn")

Section

title	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:

Name	Description
`now`	The current date at the time the page is rendered.
`startOfDay`	The date at the first millisecond on the current day.
`endOfDay`	The date at the last millisecond on the current day.
`startOfWeek`	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.
`endOfWeek`	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.
`startOfMonth`	The date at the first millisecond of the first day of the month the current day is part of.
`endOfMonth`	The date at the last millisecond of the first day of the month the current day is part of.
`startOfYear`	The date at the first millisecond of the first day of the year the current day is part of.
`endOfYear`	The date at the last millisecond of the first day of the year the current day is part of.

Note Box

title	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, use "" (empty string) as the first argument.

Version Box

title	Abbreviated Date Function Call Form
since	4.1

Since version 4.1 the abbreviated form without format argument is also supported.

Simply use only the second argument without double quotes.

Code Block

language	text

$<Date§> >= ${now(-2w)}

Example Box

The following calls are semantically identically.

Code Block

language	text

$<Date§> >= ${startOfMonth()}
$<Date§> >= ${startOfMonth("")}
$<Date§> >= ${startOfMonth("", "")}

The following calls are semantically identically, the first only available in 4.1 and above.

Code Block

language	text

$<Date§> <= ${startOfMonth(-1d)}  // 4.1 and above
$<Date§> <= ${startOfMonth("", "-1d")}

Caution Box

title	Unsupported operators: '<' and '>'

Prior to version 4.1 the operators '>' and '<' are not supported!

Please use '>=' and '<=' instead.

Section

title	Format

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

Typically use:

Format	Description
`y`	Year. Typically use "`yyyy`" for four digits (i.e. `2019`).
`M`	Month. Typically use "`MM`" for two digits (i.e. `03` and `12`).
`dd`	Day. Typically use "`dd`" for two digits (i.e. `01` and `15`).
`H`	Hours. Typically use "`HH`" for two digits (i.e. `08` and `23`).
`m`	Minutes. Typically use "`mm`" for two digits (i.e. `01` and `59`).

The default format is: "yyyyMMdd".

Note Box

title	Render Format

Note that the format is used to render the date. If the date is compared to another date the compare is not executed on the date object, but on the rendered date. Therefore the format must be comparable lexicographically. Any format would do that shows the year first, then the month (leading zero in case the month ordinal number is smaller ten, and lastly the day (again with leading zero).

Example Box

title	Compate Date with Format

Assume a document property named Date with a date value in text form: 17.11.2019

To match that date on November the 23rd in 2019 the function requires to subtract 6 days.

Code Block
$<Date> = ${now("dd.MM.yyyy", "-6d")}

In order to match the date value, the format must be specified. This is because the rendered dates are compared, not the parsed date objects.

Section

title	Increment

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

The format is:

Code Block
(+/-)nn(y\|M\|w\|d\|h\|m)

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:

ID	Description
`y`	Years
`M`	Months
`w`	Weeks
`d`	Days
`H`	Hours
`m`	Minutes

For instance:

Example Box

Code Block

language	text

+2d

5y

-10w

-2d10y

Example Box

Here are some usage examples:

Code Block

language	text

$<Date§> >= ${now("", "-2w")}
$<Date§> >= ${endOfMonth("", "1w")}
$<Date§> >= ${startOfMonth("", "+3d")}

Using date ranges:

Code Block

language	text

Date§: [${now("", "-6w")} TO ${now("", "-4w")}]

$<Date§> >= ${now("", "-6w")} AND $<Date§> <= ${now("", "-4w")}

Version Box

title	Abbreviated Date Function Call Form
since	4.1

Since version 4.1 the abbreviated form without format argument is also supported.

Instead of

Code Block

language	text

$<Date§> >= ${now("", "-2w")}
$<Date§> >= ${endOfMonth("", "1w")}
$<Date§> >= ${startOfMonth("", "+3d")}

simply write

Code Block

language	text

$<Date§> >= ${now(-2w)}
$<Date§> >= ${endOfMonth(1w)}
$<Date§> >= ${startOfMonth(+3d)}

Note that there are no double quotes around the increment specification.

Section

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

Section

title

Note Box
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.

Code Block

language	text

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

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

Caution Box

Code Block

language	text

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

See Relative Date Queries with Confluence on Atlassian Answers.

	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:

Code Block

language	text

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

Section

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

Code Block
: -Parent:[* TO *]

or

Code Block
: NOT Parent:[* TO *]

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

Tip Box
If you need to have all documents in the result

that

that actually have a parent, then use

Code Block

language	text

Parent:[* TO *]

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

Caution Box

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

Code Block

language	text

Tags = "logging" NOT ID = 3704077

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

Code Block

language	text
collapse	true

Tags = "logging" AND ID NOT 3704077

Section

title	Document Properties for Selection

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

...

Section

required-permissions	write-access
title	Notes

Section

title	References

Section

title	Resources

Tour

render-as-definition-list	true
replace-title-with-name	true

Title	Short Description
#Search
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.
Tips

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 7

New Version Current

Key

Prefix Query

Using Date Ranges

About

Keep up-to-date!

Powered by