The @Struct Annotation Type in Hibernate – Structured User-Defined Types

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):

@Entity
public class Department {
    @Id
    @GeneratedValue
    private Integer id;
    
    @Column
    private String departmentName;
    
    @Embedded
    private Manager manager;
}

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

@Embeddable
@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:

CREATE TABLE DEPRARTMENT (
  Id BIGINT, 
  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:

CREATE TABLE DEPRARTMENT (
Id BIGINT, 
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:

@Embeddable
@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:

@Entity
public class Department_JsonHolder {
    @Id
    @GeneratedValue
    private int id;
    
    @JdbcTypeCode(SqlTypes.JSON)
    @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.