Pull and Display Related Content documentation for the dotCMS Content Management System

dotCMS supports one-sided relationship fields on all Content Types. To learn how to add Relationships to a content type and use the Relationships field, see the Relationships Documentation. Mark the relationship as searchable on the content type to allow related content searches in the Content Search manager.

Searchable Relationships Field

Once relationship fields have been added on Content Types, and relationships have been added to content, then content can be queried and dynamically listed on pages. To get help building a related search query, first search for related content in the Content Search manager, and then click the down arrow to the right of the search button and then on “Show Query”

Searching for Content by Relationship

The Velocity code example below shows how to display a single related contentlet (Employee Listing), or how to set up a secondary #foreach loop to iterate over multiple related content (Locations Listing), since many employees are allowed to be related to a single location in the one-to-many relationship set up between the two content types.

<h2>Employees Listing (One Related Location)</h2>
#foreach($employee in $dotcontent.pull("+contentType:Employee +(conhost:48190c8c-42c4-46af-8d1a-0cd5db894797 conhost:SYSTEM_HOST) +Employee.location:784bebeb-ce31-414f-b7e8-41653ea9f195",3,"modDate desc"))
    <h3>$!{employee.firstName} $!{employee.lastName}</h3>
    Location: $employee.location.title

<h2>Locations Listing (Many Related Employees)</h2>
#foreach($location in $dotcontent.pull("+contentType:Location",3,"modDate desc"))
    #set($list = $!{location.employees})
    #foreach($relatedEmployee in $list)
        $relatedEmployee.firstName $relatedEmployee.lastName#if($foreach.hasNext), #end

Below is an image of the data return of the code above:

Searching for Content by Relationship

$dotcontent.pullRelated tool - DEPRECATED*

* Usage of the dotcontent.pullRelated tool has been Deprecated in favor of the one-sided content pull as shown in the documentation above. If you have old relationships on a dotCMS server that is version 5.1 or higher, then you should carefully ready the relationships migration documentation before updating existing relationships

The pullRelated methods on the ContentTool ($dotcontent.pullRelated()) allow you to retrieve content which is related to another specified piece of content.


The pullRelated method can be called in the following ways, each of which requires different arguments, and modifies the search in some ways:

Method CallDescriptionJavadocs Link
pullRelated(String relationshipName, String contentletIdentifier, boolean pullParents, int limit)Pulls all related content, using the default sort order.Javadocs
pullRelated(String relationshipName, String contentletIdentifier, boolean pullParents, int limit, String sort)Pulls all related content, sorting the results as specified by the sort parameter.Javadocs
pullRelated(String relationshipName, String contentletIdentifier, String condition, boolean pullParents, int limit, String sort)Pulls content which is both related and matches the condition parameter, sorting as specified by the sort parameter.Javadocs


The following arguments are required by different versions of the pullRelated method.

Relationship Name

You must specify the relationship name of the relationship you wish to use. The relationship name can be found by viewing the relationship in the Relationships tab.

Contentlet Identifier

You must specify the identifier of the contentlet for which related items will be returned. For example, if you wish to find all parent of a specific document, you must supply the identifier of that document. The contentlet identifier is passed as a string, and may be found by returning the id field of a content object returned by any other content pull method.


The condition field allows you to specify query terms; only content items which match the condition and which are related to the specified contentlet will be returned.


Each relationship specifies a parent-child relationship between content items. The pullParents argument specifies whether or not to pull the parent items of to the specified content. If it is set to "true", all parents of the specified item will be retrieved; if it is set to "false", all children of the specific content will be pulled instead.


Specifies the maximum number of content items to return.


The sort argument takes a string which specifies which field or fields to sort on, and the order of the sort (“asc”, which is the default, or “desc”).


Example 1: Pull Child Items

The following example gets the relationships for a piece of content with Identifier “asbd-asd-asda-asd” and requests return of 10 of the related items. The pullParents argument is set to "false", so the call returns the child items. Since no sort order is specified, the returned items will be ordered by their order on the relationship tab.

#foreach($content in $dotcontent.pullRelated("relationshipName","identifier",false,10))     

Example 2: Pull with Condition and Sort

The following example adds a query condition ("someField:someValue") and a sort order ("modDate") to sort the returned items by modification date.

#foreach($content in $dotcontent.pullRelated("relationshipName","identifier","+someField:someValue",false,10,"modDate"))

For more information regarding the pullRelated method, please see the ContentTool Javadocs.