Hibernate Natural IDs in Spring Boot

1. Overview

Some database entries possess a natural identifier, such as a book’s ISBN or a person’s SSN. In addition to the traditional database ID, Hibernate allows us to declare some of the fields as natural IDs and easily query based on these properties.

In this tutorial, we’ll discuss the @NaturalId annotation, and we’ll learn to use and implement it in a Spring Boot project.

2. Simple Natural Id

We can designate a field as a natural identifier simply by annotating it with @NaturalId. This allows us to seamlessly query the associated column using Hibernate’s API.

For the code examples in this article, we’ll use the HotelRoom and ConferenceRoom data models. In our first example, we’ll implement the ConferenceRoom entity, which can be distinguished by its unique name property:

@Entity
public class ConferenceRoom {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NaturalId
    private String name;

    private int capacity;

    public ConferenceRoom(String name, int capacity) {
        this.name = name;
        this.capacity = capacity;
    }

    protected ConferenceRoom() {
    }

    // getters
}

First, we need to annotate the name field with @NaturalId. Let’s notice that the field is immutable: It is declared in the constructor and it does not expose a setter. Additionally, Hibernate requires a no-argument constructor, but we can make it protected and avoid using it.

We can now use the bySimpleNaturalId method to easily search the database for a conference room using its name as the natural identifier:

@Service
public class HotelRoomsService {

    private final EntityManager entityManager;

    // constructor

    public Optional<ConferenceRoom> conferenceRoom(String name) {
        Session session = entityManager.unwrap(Session.class);
	return session.bySimpleNaturalId(ConferenceRoom.class)
          .loadOptional(name);
    }
}

Let’s run a test and inspect the generated SQL to confirm the expected behavior. In order to see the Hibernate/JPA SQL log, we’ll add the appropriate logging configuration:

logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE

Now, let’s call the conferenceRoom method that will query the database for the conference room with the natural id “Colorado“:

@Test
void whenWeFindBySimpleNaturalKey_thenEntityIsReturnedCorrectly() {
    conferenceRoomRepository.save(new ConferenceRoom("Colorado", 100));

    Optional<ConferenceRoom> result = service.conferenceRoom("Colorado");

    assertThat(result).isPresent()
      .hasValueSatisfying(room -> "Colorado".equals(room.getName()));
}

We can inspect the generated SQL and expect it to query the conference_room table using its natural ID, the name column:

select c1_0.id,c1_0.capacity,c1_0.name 
from conference_room c1_0 
where c1_0.name=?

3. Compound Natural Id

Natural identifiers can also consist of multiple fields. In such cases, we can annotate all the relevant fields with the @NaturalId annotation.

For instance, let’s consider the GuestRoom entity, which has a compound natural key composed of the roomNumber and floor fields:

@Entity
public class GuestRoom {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NaturalId
    private Integer roomNumber;

    @NaturalId
    private Integer floor;

    private String name;
    private int capacity;

    public GuestRoom(int roomNumber, int floor, String name, int capacity) {
        this.roomNumber = roomNumber;
        this.floor = floor;
        this.name = name;
        this.capacity = capacity;
    }

    protected GuestRoom() {
    }
    // getters
}

Similarly to the first example, we’ll now use the byNaturalId method from Hibernate’s Session. After that, we’ll use the fluent API to specify the values of the fields making up the compound key:

public Optional<GuestRoom> guestRoom(int roomNumber, int floor) {
    Session session = entityManager.unwrap(Session.class);
    return session.byNaturalId(GuestRoom.class)
      .using("roomNumber", roomNumber)
      .using("floor", floor)
      .loadOptional();
}

Now, let’s test the method by trying to query the database for the GuestRoom with the number 23, from the third floor:

@Test
void whenWeFindByNaturalKey_thenEntityIsReturnedCorrectly() {
    guestRoomJpaRepository.save(new GuestRoom(23, 3, "B-423", 4));

    Optional<GuestRoom> result = service.guestRoom(23, 3);

    assertThat(result).isPresent()
      .hasValueSatisfying(room -> "B-423".equals(room.getName()));
}

If we check the SQL now, we should see a straightforward query that uses the composite key:

select g1_0.id,g1_0.capacity,g1_0.floor,g1_0.name,g1_0.room_number 
from guest_room g1_0 
where g1_0.floor=? 
and g1_0.room_number=?

4. Integration With Spring Data

Out of the box, Spring Data‘s JpaRepository does not provide support for querying by natural identifiers. Nonetheless, we can extend these interfaces with an additional method to enable such queries. To accomplish this, we must first declare the enriched interface:

@NoRepositoryBean
public interface NaturalIdRepository<T, ID> extends JpaRepository<T, ID> {
    Optional<T> naturalId(ID naturalId);
}

After this, we’ll create a generic implementation of this interface. Additionally, we’ll need to convert the generic type to a domain entity. To achieve this, we can extend JPA’s SimpleJpaRepository, and leverage it’s getDomainClass method:

public class NaturalIdRepositoryImpl<T, ID extends Serializable> extends SimpleJpaRepository<T, ID> implements NaturalIdRepository<T, ID> {
    private final EntityManager entityManager;

    public NaturalIdRepositoryImpl(JpaEntityInformation<T, ?> entityInformation, EntityManager entityManager) {
        super(entityInformation, entityManager);
        this.entityManager = entityManager;
    }

    @Override
    public Optional<T> naturalId(ID naturalId) {
        return entityManager.unwrap(Session.class)
	  .bySimpleNaturalId(this.getDomainClass())
          .loadOptional(naturalId);
    }

}

Additionally, we’ll need to add the @EnableJpaRepositories annotation to allow Spring to scan the whole package and register our custom repository:

@Configuration
@EnableJpaRepositories(repositoryBaseClass = NaturalIdRepositoryImpl.class)
public class NaturalIdRepositoryConfig {
}

This will allow us to extend the NaturalIdRepository interface to create repositories for our entities that possess a natural id:

@Repository
public interface ConferenceRoomRepository extends NaturalIdRepository<ConferenceRoom, String> {
}

As a result, we’ll be able to use the enriched repository API and leverage the naturalId method for simple queries:

@Test
void givenNaturalIdRepository_whenWeFindBySimpleNaturalKey_thenEntityIsReturnedCorrectly() {
    conferenceRoomJpaRepository.save(new ConferenceRoom("Nevada", 200));

    Optional result = conferenceRoomRepository.naturalId("Nevada");

    assertThat(result).isPresent()
      .hasValueSatisfying(room -> "Nevada".equals(room.getName()));
}

Finally, let’s check the generated SQL statement:

select c1_0.id,c1_0.capacity,c1_0.name 
from conference_room c1_0 
where c1_0.name=?

5. Conclusion

In this article, we’ve learned about entities possessing natural identifiers, and we discovered that Hibernate’s API allows us to easily query by these special identifiers. After that, we created a generic Spring Data JPA repository and enriched it to take advantage of this feature of Hibernate.