SiteSearch Viewtool

Last Updated: Sep 16, 2021
documentation for the dotCMS Content Management System

The Site Search viewtool allows you to search for files, pages, and content on a SiteSearch index, and list all available SiteSearch indices.


MethodReturn ValueDescription
$, offset, limit)SiteSearchResults objectRun the query on the default SiteSearch index and return the specified content items.
$, query, offset, limit)SiteSearchResults objectRun the query on the SiteSearch index specified by the indexAlias, and return the specified content items.
$sitesearch.listSearchIndicies()List of StringReturns a list of all available Site Search index names.
You can pass the name of any index as the first argument to the search() method, above.

The search() method allows you to perform a search against a single site search index. Which index the search is performed against is determined by the indexAlias parameter you supply (if any); if no indexAlias parameter is supplied, the search is performed against the default SiteSearch index.


indexAliasAlias of the index where the search is to be performed.
If an alias is not specified, the default SiteSearch index will be used.
queryQuery used to perform the search.
You may use the Show Query feature to create queries that you can copy and paste directly into this view tool.
You can use the Site Search Tool to test your queries in the dotCMS backend.
offsetStart record number (for pagination).
limitNumber of results to return (for pagination).

Return Values

The search() methods return a SiteSearchResults (plural) object. The following methods are available on the returned object:

MethodValue Returned
getStart()The start record.
getTotalResults()Total number of results returned by the query.
getTook()Time it took to run the query.
getLimit()Value of the limit argument.
getOffset()Value of the offset argument.
getResults()List of search results (see below).
getMaxScore()Maxiumum search score of all the search results.
getIndex()The index where the search was performed.

The getResults() method on the SiteSearchResults object returns a list that contains one individual SiteSearchResult (singular) object for each result. The following methods are available on each individual SiteSearchResult object:

MethodValue Returned
getContent()Content object for the search result.
getFilename()File name of the search result (if appropriate to the Content Type).
getLanguage()Language (as an integer) of the Content.
getId()Identifier (id) of the Content.
getHost()Host where the Content is stored.
getUri()URI of the Content (the path to the Content within the dotCMS asset tree).
getUrl()URL of the Content (the browser URL to access the Content).
getMimeType()mimeType of the Content.
getTitle()Content Title field.
getDescription()Content Description field.
getKeywords()Content keywords field.
getAuthor()Content author.
getContentLength()Content length (in bytes).
getModified()Date the Content was last modified.
getScore()Search score for the Content.

Common Query Terms

The SiteSearch index contains certain common fields for all content items included in the index. You can include the following keywords in your query to search on these fields:

  • content
  • filename
  • id
  • host
  • uri
  • url
  • mimeType
  • title
  • description
  • keywords
  • author
  • contentLength
  • modified
  • score
  • language

For more information on query syntax, please see the Content Search Syntax documentation.

Displaying Results

The results are returned in an object that contains properties of the search itself (such as the index alias), and a list of search results, one list item per content item that matched the query (up to the specified limit). Each item in the search results contains all of the properties that can be used to query the index, plus a highlights property.

For details on what specific properties are returned with the search results, please see the Velocity Example, below.

Displaying Highlights (Matches)

Each search result includes a highlights property. This is a list, which contains one entry for each time the content matched the query terms. Each highlight consists of a block of text surrounding the match for context, and the portion of that text which matched the query terms is highlighted (using HTML tags).

The text in each highlight is trimmed to 255 characters; if the field which contained the match is shorter than 255 characters, then the entire contents of the field will be included.

The following code snipped demonstrates how to display all the highlights for a single search result (stored in a Velocity variable named $result):

    #foreach($highlight in $result.highlights)

If you only want to display the first highlight, you can add a Velocity #break command into the loop as follows:

    #foreach($highlight in $result.highlights)

Displaying Content Type Fields

The Site Search results contain values that are shared by all content items, but do not contain custom Content Type fields you've added to your Content Types. However, you can display all the fields of your Content Type by calling the $dotcontent.find() method to retrieve the full content object, as in the following code snippet:

$dotcontent.find( "$" )


The following examples demonstrate how to use the SiteSearch viewtool to query and display results on your site.

Perform a Search

Example Queries

The following example queries demonstrate several different ways you can create queries for use with the Site Search view tool:

  • Search for content that matches a keyword and a specific URI:
    +content:dotcms +uri:/events/
  • Search for content that matches a list of mimeTypes:
    +(mimeType:text/html mimeType:image/jpeg)
  • Search for content that matches a description OR author:
    +(description:dotcms* author:jason*)
  • Search for content that matches a description OR author in a particular language:
    +(description:dotcms* author:jason*) +language:1

Example Velocity Code

The following code performs a query using the SiteSearch Tool, accessed the contents of the returned SiteSearchResults object, and displays each individual content item returned by the query.

#set($searchresults = $$indexAlias,$query,0,100))

<p>Start: $searchresults.start</p>
<p>Total Results: $searchresults.totalResults</p>
<p>Took: $searchresults.took</p>
<p>Limit: $searchresults.limit</p>
<p>Offset: $searchresults.offset</p>
<p>MaxScore: $searchresults.maxScore</p>
<p>Index: $searchresults.index</p>

<p>Search Results: $searchresults.results.size()</p>
#foreach($result in $searchresults.results)
        <li>Description: $result.description</li>
    #set( $contentObj = $dotcontent.find( "$" ) )
        <li>tags: $contentObj.tags</li>
        #foreach($highlight in $result.highlights)

List Site Search Indices

<h3>Site Search Indexes:</h3>
#foreach( $indexAlias in $sitesearch.listSearchIndicies() )

Toolbox.xml Configuration

The following example shows how the Site Search viewtool is mapped in the toolbox.xml file:


On this page


We Dig Feedback

Selected excerpt: