Using Enum in Spring Data JPA Queries

1. Overview

When building our persistence layer with Spring Data JPA, we often work with entities with enum fields. These enum fields represent a fixed set of constants, such as the status of an order, the role of a user, or the stage of an article in a publishing system.

Querying entities based on their enum fields is a common requirement, and Spring Data JPA provides several ways to accomplish this.

In this tutorial, we’ll explore how we can query enum fields declared in our entity classes using standard JPA methods and native queries.

2. Application Setup

2.1. Data Model

First, let’s define our data model, including an enum field. The central entity in our example is the Article class, which declares an enum field ArticleStage to represent the different stages an article can be in:

public enum ArticleStage {
    TODO, IN_PROGRESS, PUBLISHED;
}

The ArticleStage enum holds three possible stages, representing the lifecycle of an article from its initial creation to its final published state.

Next, let’s create the Article entity class with the ArticleStage enum field:

@Entity
@Table(name = "articles")
public class Article {

    @Id
    private UUID id;

    private String title;

    private String author;

    @Enumerated(EnumType.STRING)
    private ArticleStage stage;

    // standard constructors, getters and setters
}

We map our Article entity class to the articles database table. Additionally, we use the @Enumerated annotation to specify that the stage field should be persisted as a string in the database.

2.2. Repository Layer

With our data model defined, we can now create a repository interface that extends JpaRepository to interact with our database:

@Repository
public interface ArticleRepository extends JpaRepository<Article, UUID> {
}

In the upcoming sections, we’ll be adding query methods to this interface to explore different ways of querying our Article entity by its enum field.

3. Standard JPA Query Methods

Spring Data JPA allows us to define derived query methods in our repository interfaces using method names. This approach works perfectly for simple queries.

Let’s examine how this can be used to query the enum field in our entity class.

3.1. Querying by a Single Enum Value

We can find articles by a single ArticleStage enum value by defining a method in our ArticleRepository interface:

List<Article> findByStage(ArticleStage stage);

Spring Data JPA will generate the appropriate SQL query based on the method name.

We can also combine the stage parameter with other fields to create more specific queries. For example, we can declare a method to find an article by its title and stage:

Article findByTitleAndStage(String title, ArticleStage stage);

We’ll use Instancio to generate test Article data and test these queries:

Article article = Instancio.create(Article.class);
articleRepository.save(article);

List<Article> retrievedArticles = articleRepository.findByStage(article.getStage());

assertThat(retrievedArticles).element(0).usingRecursiveComparison().isEqualTo(article);

Article article = Instancio.create(Article.class);
articleRepository.save(article);

Article retrievedArticle = articleRepository.findByTitleAndStage(article.getTitle(), article.getStage());

assertThat(retrievedArticle).usingRecursiveComparison().isEqualTo(article);

3.2. Querying by Multiple Enum Values

We can also find articles by multiple ArticleStage enum values:

List<Article> findByStageIn(List<ArticleStage> stages);

Spring Data JPA will generate an SQL query that uses the IN clause to find articles whose stage matches any of the provided values.

To verify that our declared method works as expected, let’s test it:

List<Article> articles = Instancio.of(Article.class).stream().limit(100).toList();
articleRepository.saveAll(articles);

List<ArticleStage> stagesToQuery = List.of(ArticleStage.TODO, ArticleStage.IN_PROGRESS);
List<Article> retrievedArticles = articleRepository.findByStageIn(stagesToQuery);

assertThat(retrievedArticles)
  .isNotEmpty()
  .extracting(Article::getStage)
  .doesNotContain(ArticleStage.PUBLISHED)
  .hasSameElementsAs(stagesToQuery);

4. Native Queries

In addition to the standard JPA methods we explored in the previous section, Spring Data JPA also supports native SQL queries. Native queries are useful for executing complex SQL queries and allow us to invoke database-specific functions.

Moreover, we can use SpEL (Spring Expression Language) with the @Query annotation to construct dynamic queries based on method parameters.

Let’s see how we can use native queries with the SpEL to query our entity class Article by its ArticleStage enum value.

4.1. Querying by a Single Enum Value

To query article records by a single enum value using a native query, we can define a method in our ArticleRepository interface and annotate it with the @Query annotation:

@Query(nativeQuery = true, value = "SELECT * FROM articles WHERE stage = :#{#stage?.name()}")
List<Article> getByStage(@Param("stage") ArticleStage stage);

We set the nativeQuery attribute to true to indicate that we’re using a native SQL query instead of the default JPQL definition.

We use a SpEL expression :#{#stage?.name()} in the query to refer to the enum value that is passed to the method parameter. The ? operator in the expression is used to handle null input gracefully.

Let’s verify that our native query method works as expected:

Article article = Instancio.create(Article.class);
articleRepository.save(article);

List<Article> retrievedArticles = articleRepository.getByStage(article.getStage());

assertThat(retrievedArticles).element(0).usingRecursiveComparison().isEqualTo(article);

4.2. Querying by Multiple Enum Values

@Query(nativeQuery = true, value = "SELECT * FROM articles WHERE stage IN (:#{#stages.![name()]})")
List<Article> getByStageIn(@Param("stages") List<ArticleStage> stages);

To achieve this scenario, we use the IN clause in our SQL query to fetch articles whose stage matches any of the provided values.

The SpEL expression #stages.![name()] transforms the list of enum values into a list of strings representing their names.

Let’s see the behavior of this method:

List<Article> articles = Instancio.of(Article.class).stream().limit(100).toList();
articleRepository.saveAll(articles);

List<ArticleStage> stagesToQuery = List.of(ArticleStage.TODO, ArticleStage.IN_PROGRESS);
List<Article> retrievedArticles = articleRepository.findByStageIn(stagesToQuery);

assertThat(retrievedArticles)
  .isNotEmpty()
  .extracting(Article::getStage)
  .doesNotContain(ArticleStage.PUBLISHED)
  .hasSameElementsAs(stagesToQuery);

5. Conclusion

In this article, we explored how to query enum fields in our entity classes using Spring Data JPA. We’ve looked at both standard JPA methods and native queries with SpEL to achieve this.

We’ve learned how to query entities using both single and multiple enum values. The standard JPA methods provide a clean and straightforward way to query enum fields, while native queries offer more control and flexibility to execute complex SQL queries.