How to map a String JPA property to a JSON column using Hibernate

Imagine having a tool that can automatically detect if you are using JPA and Hibernate properly. Hypersistence Optimizer is that tool!

Introduction

In this article, I want to show you how you can map a String JPA property to a JSON database column using the hibernate-types open-source project.

Although it’s probably more common to use a JsonNode or POJO (Plain Old Java Object) on the Java side, the hibernate-types framework is very flexible and allows you to use a String JPA property type to represent a JSON structure.

Domain Model

Considering we have a book database table that defines a properties column of the jsonb PostgreSQL type.

Book table

The associated Book JPA entity can be mapped as follows:

@Entity(name = "Book")
@Table(name = "book")
@TypeDef(
    name = "jsonb", 
    typeClass = JsonBinaryType.class
)
public static class Book {

    @Id
    @GeneratedValue
    private Long id;

    @NaturalId
    private String isbn;

    @Type(type = "jsonb")
    @Column(columnDefinition = "jsonb")
    private String properties;

    //Getters and setters omitted for brevity
}

The isbn property is mapped using the Hibernate-specific @NaturalId annotation which allows you to retrieve the entity by its natural identifier.

The properties JPA attribute encodes various book-related properties in a JSON String object. From the JPA @Column definition, we can see that the associated database column is of the type jsonb.

Now, since Hibernate does not provide a native Type to handle JSON database columns, we need to need to use the JsonBinaryType offered by the hibernate-types library.

To use the hibernate-types library in your project, just add the following Maven dependency:

<dependency>
    <groupId>com.vladmihalcea</groupId>
    <artifactId>hibernate-types-52</artifactId>
    <version>${hibernate-types.version}</version>
</dependency>

If you’re using an older version of Hibernate, go to the hibernate-types GitHub repository and find the matching hibernate-types dependency for your current Hibernate version.

Testing time

When persisting the following Book entity:

entityManager.persist(
    new Book()
        .setIsbn("978-9730228236")
        .setProperties(
            "{" +
            "   \"title\": \"High-Performance Java Persistence\"," +
            "   \"author\": \"Vlad Mihalcea\"," +
            "   \"publisher\": \"Amazon\"," +
            "   \"price\": 44.99" +
            "}"
        )
);

Hibernate generates the following SQL INSERT statement:

INSERT INTO book (
    isbn, 
    properties, 
    id
) 
VALUES (
    '978-9730228236', 
    '{"title":"High-Performance Java Persistence","author":"Vlad Mihalcea","publisher":"Amazon","price":44.99}', 
    1
)

The JsonBinaryType binds the JSON String using the setObject method of the PreparedStatement object.

Notice the Fluent-style API used when creating the Book entity. For more details about building entities using a Fluent-style API, check out this article.

Now, when fetching the previously persisted Book entity:

Book book = entityManager
    .unwrap(Session.class)
    .bySimpleNaturalId(Book.class)
    .load("978-9730228236");

assertTrue(book.getProperties().contains("\"price\": 44.99"));

We can see that the properties attribute is properly populated by the JsonBinaryType.

Cool, right?

If you enjoyed this article, I bet you are going to love my Book and Video Courses as well.

Conclusion

Although creating a custom Hibernate Type is straightforward, it’s much more convenient to use the hibernate-types open-source project since you only need to add one dependency and specify which custom Type you want to use via the @TypeDef annotation.

FREE EBOOK
Newsletter logo
10 000 readers have found this blog worth following!

If you subscribe to my newsletter, you'll get:
  • A free sample of my Video Course about running Integration tests at warp-speed using Docker and tmpfs
  • 3 chapters from my book, High-Performance Java Persistence,
  • a 10% discount coupon for my book.

13 Comments on “How to map a String JPA property to a JSON column using Hibernate

  1. I am getting an exception as given below when I try to retrieve the data by using the findById(id) method.

    org.springframework.dao.InvalidDataAccessApiUsageException: The given string value: {“price”: 25, “title”: “ashar”, “author”: “Vlad Mihalcea”, “publisher”: “Amazon”} cannot be transformed to Json object;

    • It works just fine on my High-Performance Java Persistence GitHub repository, so just compare your code with mine and see why yours does not work.

    • What you see in pgAdmin is the conversion that the UI tool makes it so that the binary format is humanly readable.

  2. Thanks for the article,

    I am able to add Postgres column type as jsonb. But it contains the escape character() also in the DB. Due to this not able to query through the json. The JSON data inside the table is as given below.

    “{\”title\”:\”qwert\”,\”author\”:\”Vlad Mihalcea\”,\”publisher\”:\”Amazon\”,\”price\”:25}”

    So in the jsonb column, it’s getting added as string only. am I missing something?

    • Jsonb stores the data in binary form, so there will be no escape character. Check out the Hibernate Types GitHub repository for more details.

    • What plugin are you talking about? This is just a jar dependency you can get from Maven Central, which works just fine with Gradle too.

  3. Great article.

    I think it should also address the difficulty for searching (like queries based on the json columns), and how this will be RDBMS specific.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.