Query API

Advanced Velocity Workshop #LiveFromRTC2019


Cascade v7.4+

Allows a query function that searches, filters, and sorts assets using a number of properties, with the returned collection containing Cascade API objects.

Dynamically Locates Assets

Can include non-indexable and non-publishable assets.

No Index Blocks

Like the Locator Tool, it requires no XML data, so no index block is needed.

Basic Syntax

Initialize Method:

Create and initialize the query object.


Execute Method:

After applying filtering options, execute the query to collect results.


Basic Syntax: Search, Filter, and Sort

Declaring a Query

All search, filter, and sort methods and properties are set using the Java dot notation. Searching can only be done on a collection of shared metadata set or content type.



The path argument will be in the form of a string that points to the path of the metadata set or content type.

For the remaing examples, we will capture the initialization of the query object in a variable called $query. Note that the execute() method is not done until all criteria are set.


#set($query = $_.query().byMetadataSet("News Article"))


Search & Filter Options

Search in a Single Site or Across Sites

Queried results can come from a particular site or across all sites. There are two methods to handle this filter. 

Example: Specify a Particular Site

#set($query = $query.siteName(SITENAME))

Example: Search Across All Sites

#set($query = $query.searchAcrossAllSites())

Filter by Metadata

To filter by dynamic metadata, use the hasMetadata() or hasAnyMetadataValues() method. 

Example: Metadata Filter for Single Value

#set($query = $query.hasMetadata(NAME, VALUE))

Example Metadata Filter for Multiple Values

#set($query = $query.hasAnyMetadataValues(NAME, ["VALUE1", "VALUE2"]))

Max Results

The number of assets returned in a query collection is limited to 100 by default. This number can increased or decreased using the maxResults(INT) method. There is currently a hard maximum limit of 2000 since v8.9.


#set($query = $query.maxResults(200))

Sorting Results

Sorting the Results

The Query Tool provides two sort methods. The sortBy() method takes in the field name as a string. Fields that can be used are:

  • Static Metadata Fields ("author", "description", "displayName", "endDate", "keywords", "reviewDate", "startDate", "summary", "teaser", "title")
  • Last Modified Date ("modified")
  • Creation Date ("created")
  • System Name ("name")
  • Path ("path")

The sortDirection() takes in either the string "asc" or "desc" as an argument.


Example: Sort By

#set($query = $query.sortBy("startDate"))

Example: Sort Direction

#set($query = $query.sortDirection("asc")) 


"Include" Filtering Options

Seven additional methods are provided to explicitly include or exclude assets that are of a particular entity type, set to be indexable, or set to be publishable. These methods all take in a boolean as an argument and their defaults are listed to the right.


Example: Include by Entity Type

includePages() => true

includeBlocks() => true

includeFiles() => false

includeFolders() => true

includeSymlinks() => true

indexableOnly() => true

publishableOnly() => false


Query API Exercises # 7 - 8

Get Started

Extra Practice (Take Home)

Query API Exercise # 9

Get Started

More Resources