Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

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 code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW