A property reference is defined by ${property name}. A deep link is an expression where the property value contains reference uses an arrow (->) requesting to dereference to reference another property value: ${A->B}. It implies that the property A expects a document with a property named B. By dereferencing the property value of B replaces the property reference.

Deep links can be used in Select parameters and  and Where parameters of queries. In a Select parameter the macro simply dereferences the value by following the property chain. Person->Address->City simply renders the value of the City property that is referenced by the Person property via the Address property.

The Where parameter value is a conjunction of predicates. A predicate has two sides. The left side is the name of a property of a document in the result set. This property must match the right side of the predicate:

Name=Jane

The left right side can contain a reference to the current document, the document that contains the macro with the Where parameter. The syntax is slightly different, since we want to express an exact match (see Search Tips for more information on search syntax):

$<Name>=[${Sister->Name}]

Dereferencing the right side is easy, since the right side points to the current document. So this is not different to the task we already solved by using deep links in Selects.

For deep links on the left side of a predicate, the referenced value needs to be materialized. We need to match a document with Lucene and we do not want to dereference a deep link on a collection of possible matches on the returned result set. This might be okay if the number of possible hits is already quite small before we apply the deep link constraints. In case the deep link is the only clue constraint for the query, this would mean that we need to check every document on Confluence in this way. By materializing the property, we effectively store the result of ${Sister→Name} by a property name (like Sister's Name).

In the past materializing properties had to be done manually by adding an additional property to a document at the design time of the document type (or doctype for short). So if you would like the birthday of a person in a stakeholder document, where the stakeholder already has a reference to a single person, the additional property on the stakeholder would use the Display Document Property Ref Macro to conjure the person's birthday value to the stakeholder's property (see Materialize Properties for example).

Since version 4.5 materializing is much easier, but is still required in order to use deep links on the left side of the predicate. This tips gives a short overview over deep links on both sides of the predicate.