Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. The Developer Center continues to support Commerce 6.13.0 through 7.4.1.Visit new site

QueryService Relations

QueryService Relations

A QueryService Relation defines a domain object's query relationships. Relations encapsulate the knowledge QueryService requires for creating JPQL queries, such as column names, aliases, and how joins are handled.

Using Relations

When building the QueryCriteria, you can use Relations to identify the properties and values filtered by the query. For example, you use a Relation to query for Products with a specific Product UID:

CriteriaBuilder.criteriaFor(Product.class)
.with(ProductRelation.having().uids(productUid))
.returning(ResultType.ENTITY)

Relations are inserted into the QueryCriteria with the CriteriaBuilder's with() method. You can insert multiple Relations into the QueryCriteria by chaining with() methods. For example, the following query looks for Products with with a specific Brand UID and Category UID:

CriteriaBuilder.criteriaFor(Product.class)
.with(CategoryRelation.having().uids(categoryUid))
.with(BrandRelation.having().uids(brandUid))
.returning(ResultType.ENTITY)

QueryService requires a valid Relation between the object you are querying and the object encapsulated by the Relation. A Relation is valid if the object encapsulated by the Relation is a property of the object being queried. For example, a BrandRelation is valid when you query a Product since Product has a Brand property. However, a ContentSpaceRelation is invalid since Product and ContentSpace are unrelated.

Building a Relation

Creating the Relation object

To create a relation object, you need to call the Relation class' static having() method.

Identifier Methods

To specify the object properties a query looks up, you call a Relation's identifier methods. Each identifier method maps to a property of the Relation's domain object and provides information on how to query the property.

Out of the box, Elastic Path Relation classes support four identifier methods for querying object properties:

Property Identifier Method
UID uids(Long)
GUID guids(String)
Code codes(String)
Name names(String)

For example, to query for a Store with a specific name, use the StoreRelation's names() identifier method:

StoreRelation.having().names("SnapItUp")