1. Overview

In this tutorial, we’ll review Hibernate’s @Struct annotation which let’s developers create structured user-defined types.

Support for structured user-defined types, a.k.a structured types, was introduced in the SQL:1999 standard, which was a feature of object-relational (ORM) databases.

Structured or composite types have their use cases, especially since support for JSON was introduced in the SQL:2016 standard. Values of these structured types provide access to their sub-parts and do not have an identifier or primary key like a row in a table.

2. Struct Mapping

Hibernate lets you specify structured types through the annotation type @Struct for the class annotated with the @Embeddable annotation or the @Embedded attribute.

2.1. @Struct for Mapping Structured Types

Consider the below example of a Department class which has an @Embedded Manager class (a structured type):

public class Department {
    private Integer id;
    private String departmentName;
    private Manager manager;

The Manager class defined with @Struct annotation is given below:

@Struct(name = "Department_Manager_Type", attributes = {"firstName", "lastName", "qualification"})
public class Manager {
    private String firstName;
    private String lastName;
    private String qualification;

2.2. The Difference Between @Embeddable and @Struct Annotations

A class annotated with @Struct maps the class to the structured user-defined type in the database. For example, without the @Struct annotation, the @Embedded Manager object, despite being a separate type, will be part in the Department table as shown in the DDL below:

  DepartmentName VARCHAR,
  FirstName VARCHAR,
  LastName VARCHAR,
  Qualification VARCHAR

The Manager class, with the @Struct annotation, will produce a user-defined type similar to:

create type Department_Manager_Type as (
    firstName VARCHAR,
    lastName VARCHAR,
    qualification VARCHAR 

With the added @Struct annotation, the Department object as shown in the DDL below:

DepartmentName VARCHAR,
Manager Department_Manager_Type

2.3. @Struct Annotation and Order of Attributes

Since a structured type has multiple attributes, the order of the attributes is very important for mapping data to the right attributes. One way to define the order of attributes is through the “attributes” field of the @Struct annotation.

In the Manager class above, you can see the “attributes” field of the @Struct annotation, which specifies that Hibernate expects the order of the Manager attributes (while Serializing and De-serializing it) to be “firstName”, “lastName” and finally “qualification”.

The second way to define the order of attributes is by using a Java record to implicitly specify the order through the canonical constructor, for example:

@Struct(name = "Department_Manager")
public record Manager(String lastName, String firstName, String qualification) {}

Above, the Manager record attributes will have the following order: “lastName”, “firstName” and “qualification”.

3. JSON Mapping

Since JSON is a predefined unstructured type, no type name or attribute order has to be defined. Mapping an @Embeddable as JSON can be done by annotating the embedded field/property with @JdbcTypeCode(SqlTypes.JSON).

For example, the below class holds a Manager object which is also a JSON unstructured type:

public class Department_JsonHolder {
    private int id;
    @Column(name = "department_manager_json")
    private Manager manager;

Below is the expected DDL code for the class above:

create table Department_JsonHolder as (
    id int not null primary key,
    department_manager_json json

Below is the example HQL query to select attributes from the department_manager_json column:

select djh.manager.firstName, djh.manager.lastName, djh.manager.qualifications
from department_jsonholder djh

4. Conclusion

The difference between an @Embeddable and an @Embeddable @Struct is that the latter is actually a user-defined type in the underlying database. Although many databases support user-defined types, the hibernate dialects that have support for @Struct annotation are:

  • Oracle
  • DB2
  • PostgreSQL

In this article, we discussed Hibernate’s @Struct annotation, how to use it, and when to add it to a domain class.

The source code for the article is available over on GitHub.

Course – LSD (cat=Persistence)

Get started with Spring Data JPA through the reference Learn Spring Data JPA course:

res – Persistence (eBook) (cat=Persistence)
Notify of
Inline Feedbacks
View all comments