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

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Building a Query with QueryService

Building a Query with QueryService

QueryService saves you from having to create statements to query the database. By creating QueryCriteria objects, you can query the database without needing to know the database schema. The QueryCriteria object is built by a CriteriaBuilder and is automatically converted into JPQL and executed by the QueryService.

Below is a query example that returns products with a particular category UID:

QueryResult<Product> queryResult = queryService.query(
     CriteriaBuilder.criteriaFor(Product.class)
     .with(CategoryRelation.having().uids(categoryUid))
     .usingLoadTuner(loadTuner)
     .returning(ResultType.ENTITY)
 );

Components of the QueryCriteria Object

QueryCriteria objects have five different components, as shown in the image below:

exampleQuery

1. Specify the Domain Class

To create a QueryCriteria object, you need to call the CriteriaBuilder's static criteriaFor() method.

The QueryCriteria's first component specifies the domain class. This domain class must match the generic type of the QueryService implementation to properly generate the JPQL query. For example, ProductQueryService, which implements the QueryService<Product> interface, needs Product QueryCriteria to create Product queries.

2. Define the Query Relations

To filter a query's results against particular properties, you can define Relations.

The QueryCriteria's second component is optional and specifies the properties and values searched by the query. The CriteriaBuilder's with() method takes in a Relation object, which identifies a property and value. Relations are explained in further detail in QueryService Relations. You can chain multiple with() statements together to refine your queries.

In the example's with() statement, the CategoryRelation object is used to query for Products with a specific category UID.

3. Define the Date Range

To filter a query's results within a specific time frame, you can use either the CriteriaBuilder's inDateRange() or modifiedAfter() method.

The QueryCriteria's third component is optional and restricts the results returned by date. The modifiedAfter() method takes in a single Date and returns results that were modified after the given date. The inDateRange() method takes in a start Date and an end Date and returns results that were modified within the given time frame.

4. Specify a Load Tuner

To control the amount of associated object data that is retrieved from the database, you can specify a load tuner with CriteriaBuilder's usingLoadTuner() method.

The QueryCriteria's fourth component is optional. By using a load tuner, you avoid retrieving large object graphs when you only need a subset of the data. For example, a product has a brand, category, images, and skus. If you are querying products for brand, then you can use a load tuner to avoid retrieving product images.

Note:

To use a load tuner in QueryService, you must define the load tuner bean in the Elastic Path core. You can define domain level load tuners in ep-core/src/main/resources/spring/service/service.xml and persistence level load tuners in ep-core/src/main/resources/spring/dataaccess/dao.xml.

5. Query Return Type

To specify the type of results the query returns, you need to call the CriteriaBuilder's returning() method.

The QueryCriteria's fifth component specifies the query's ResultType. Out-of-the-box, Elastic Path supports five result types:

ResultType QueryResult Generic Type Description
ResultType.ENTITY The domain class. (eg. Product) Returns the entity objects. For example, a Product query with ResultType.ENTITY returns Product objects.
ResultType.UID long Returns the objects' uidPk.
ResultType.GUID String Returns the objects' GUID.
ResultType.CONDITIONAL boolean Returns a boolean result, indicating the queried object exists.
ResultType.DATE_RESULT Date Returns a date result.

When building a query, you must specify the generic type of the QueryResult as results are returned in a List. This generic type depends on the ResultType returned by the query. Queries return an empty list if no results are found.