Guide to @EmbeddedTable in Hibernate

1. Overview

The @EmbeddedTable annotation is a new Hibernate feature that simplifies the logic of mapping an embedded object to a secondary table.

In this short tutorial, we’ll shed light on the annotation and delve into its usage. First, we’ll start with some insight into the motivation behind @EmbeddedTable. Then, we’ll demonstrate how to use it in practice.

2. The Problem With Traditional Mapping

Before this new annotation, JPA provided multiple annotations to map a single entity into multiple tables. However, this traditional approach requires @SecondaryTable, @Embedded, @Embeddable, and multiple @AttributeOverride annotations to override each column individually. This can quickly become verbose as the number of columns grows.

Let’s say we have a single Person entity that stores personal and address information. Here, we assume that we want to store the address details in a separate secondary table.

First, let’s create the Address object we want to embed inside the Person entity:

@Embeddable
public class Address {
	
    private String street;
    private String city;
    private String code;

    // setters
    
}

Now, we create the Person entity:

@Entity
@SecondaryTable(name = "person_address")
public class Person {
    
    @Id
    private int id;
    
    @Column(name= "first_name")
    private String firstName;
    
    @Column(name = "last_name")
    private String lastName;
    
    @Embedded 
    private Address address;

    // setters

}

That’s not all, as mapping the Address fields to a secondary table requires the @AttributeOverride annotation for each field:

@Embedded 
@AttributeOverride(name = "street", column = @Column(table = "person_address")) 
@AttributeOverride(name = "city", column = @Column(table = "person_address"))
@AttributeOverride(name = "code", column = @Column(table = "person_address"))
private Address address;

This approach quickly becomes cumbersome and error-prone since missing a single override can silently map a column to the wrong table. So, this is where @EmbeddedTable comes into play.

3. Using @EmbeddedTable

Starting with Hibernate 7.2, we can implement the same mapping we did in the previous section far more concisely with @EmbeddedTable:

@EmbeddedTable(value = "person_address")
private Address address;

In a nutshell, Hibernate automatically maps every field of the embedded object Address to the specified secondary table person_address without overriding each one individually.

This is particularly useful when dealing with large embeddable objects containing several fields.

So, let’s add a test case to confirm that everything works:

@Test
void whenUsingEmbeddedTableThenMapIntoTwoSeparateTables() {
    Address address = new Address();
    address.setStreet("12 Av. Tamassint center");
    address.setCity("Tamassint");
    address.setCode("10000");

    Person person = new Person();
    person.setId(1);
    person.setFirstName("Azhrioun");
    person.setLastName("Abderrahim");
    person.setAddress(address);

    session.persist(person);
    session.flush();

    Object[] addressRow = (Object[]) session.createNativeQuery(
      "select street, city from person_address",
      Object[].class
    ).uniqueResult();

    assertEquals("12 Av. Tamassint center", addressRow[0]);
    assertEquals("Tamassint", addressRow[1]);

    Object[] personRow = (Object[]) session.createNativeQuery(
      "select first_name, last_name from person",
      Object[].class
    ).uniqueResult();

    assertEquals("Azhrioun", personRow[0]);
    assertEquals("Abderrahim", personRow[1]);
}

As expected, the test case runs successfully.

4. The Limitations

Although convenient, there are a couple of points worth keeping in mind when using @EmbeddedTable.

First, it’s a Hibernate-specific annotation and not part of the Jakarta Persistence specification. If portability across JPA providers matters, the @AttributeOverride annotation is always the safer choice.

Additionally, @EmbeddedTable is marked @Incubating, which means the API is still evolving and not yet considered stable and mature.

Typically, @EmbeddedTable is intended for top-level embedded objects. So, using it on nested objects isn’t supported yet.

5. Conclusion

In this short article, we explored the new Hibernate @EmbeddedTable annotation.

Along the way, we learned that it provides a cleaner alternative to multiple @AttributeOverride annotations when mapping embedded objects to secondary tables.

The full source is available over on GitHub.