SpEL support in Spring Data JPA @Query definitions

Engineering | Thomas Darimont | July 15, 2014 | ...

Spring Data JPA allows manually defining the query to be executed by a repository method using the @Query annotation. Unfortunately parameter binding in JPQL is quite limited only allowing you to set a value and providing some type conversion. The latest Spring Data JPA M1 release of the Evans release train eases this pain by adding support for using SpEL expressions to use dynamically bound parameters within statements in @Query annotations which provides additional flexibility when defining queries manually. In this blog post, I am going to introduce you to the capabilities of this feature.

Method parameter expressions

SpEL support provides access to the query method arguments. This allows you to either simply bind the parameter as is or perform additional operations before binding.

@Query("select u from User u where u.age = ?#{[0]}")
List<User> findUsersByAge(int age);

@Query("select u from User u where u.firstname = :#{#customer.firstname}")
List<User> findUsersByCustomersFirstname(@Param("customer") Customer customer);

Parameters are exposed for indexed access ([0] in the first method) or via the name declared using @Param. The actual SpEL expression binding is either triggered by ?# or :#. We support both types to allow you to be consistent to standard JPQL parameter bindings that also might occur in the query definition. Parameters of special types like Sort and ```Pageable`` are exposed with their simple class names as variables.

Advanced SpEL expressions

While advanced parameter binding is a very useful feature, the real power of SpEL stems from the fact, that the expressions can refer to framework abstractions or other application components. A very common scenario for SpEL is the definition of security constraints. So it would be cool if we could restrict a query to only return results related to the currently authenticated user:

@Query("select u from User u where u.emailAddress = ?#{principal.emailAddress}")
List<User> findCurrentUserWithCustomQuery();

As you can see we refer to a property of Spring Security's principal. So how does the Spring Data SpEL support integrate with Spring Security.

SpEL EvaluationContext extension model

Spring Data exposes an extension point EvaluationContextExtension. The interface allows implementors to customize the EvaluationContext in a very detailed way but for convenience, we provide a EvaluationContextExtensionSupport base class to conveniently let you only implement the parts you're interested in:

class SecurityEvaluationContextExtension extends EvaluationContextExtensionSupport {

  public String getExtensionId() {
    return "security";

  public SecurityExpressionRoot getRootObject() {
    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
    return new SecurityExpressionRoot(authentication) {};

For our Spring Security extension we extend EvaluationContextExtensionSupport and override the getRootObject() method and return a new SecurityExpressionRoot instance which exposes all the security properties and expressions you already know from usage in @PreAuthorize. This step also makes them available in SpEL expressions in our @Query annotation.

The final step we need to take is to register the security extension as a bean:

class SecurityConfiguration {

    EvaluationContextExtension securityExtension() {
        return new SecurityEvaluationContextExtension();

Spring Data JPA will pick up all beans of type EvaluationContextExtension and use those to prepare the EvaluationContext to be used to evaluate the SpEL expression defined in @Query.

The extension in place will now let you leverage the full power of the Spring Security SpEL functions. Imagine a repository query method that shall return the BusinessObjects which the current user is owner of or all BusinessObjects if the current user is admin. The query method definition would look like this:

interface SecureBusinessObjectRepository extends Repository<BusinessObject,Long>{

    @Query("select o from BusinessObject o where o.owner.emailAddress like "+
      "?#{hasRole('ROLE_ADMIN') ? '%' : principal.emailAddress}")
    List<BusinessObject> findBusinessObjectsForCurrentUser();

You can find the working examples of the snippets seen here in the Spring-Data-Examples repository.

Sophisticated use cases

Often new features enable ways to do things that one thought weren't possible before - an example for this is pagination in native queries. Since this mechanism exposes special parameter types like Sortor Pageable as well, we're now able to use pagination in native queries. An example for this can be found here UserRepository.

Whats next?

Currently we are investigating a more tighter integration of Spring Security into Spring Data. We're also working on adding support for SpEL capabilities for other Spring Data modules.

But now it's your turn - please let us know what you think in the comments below of file a feature request in our JIRA.

SpringOne 2GX 2014

SpringOne 2GX 2014 is getting close.

If you want to learn more about Spring Data, be sure to register for this year's SpringOne conference. The schedule contains a lot of data-related talks to introduce you to the latest features we're going to ship with Evans.

Get the Spring newsletter

Thank you!

Get ahead

VMware offers training and certification to turbo-charge your progress.

Learn more

Get support

Spring Runtime offers support and binaries for OpenJDK™, Spring, and Apache Tomcat® in one simple subscription.

Learn more

Upcoming events

Check out all the upcoming events in the Spring community.

View all