Querying JSONB Columns Using Spring Data JPA

1. Introduction

Spring Data JPA provides a powerful abstraction layer for interacting with relational databases. However, traditional relational tables might not be ideal for storing complex, semi-structured data like product details or user preferences. This is where JSONB data types come in. In this tutorial, we’ll explore various approaches for querying JSONB columns using Spring Data JPA.

2. JSONB Columns

JSONB (JavaScript Object Notation for Databases) is a data type specifically designed for storing JSON data within relational databases like PostgreSQL. It allows us to represent complex data structures with key-value pairs and nested objects within a single column. In conjunction with the JPA provider (such as Hibernate), Spring Data JPA allows us to map these JSONB columns to attributes within our entity classes.

3. Mapping JSONB Columns

We can use the @Column annotation with the columnDefinition attribute to explicitly define the column type in the entity class:

@Column(columnDefinition = "jsonb")
private String attributes;

This approach is primarily relevant to PostgreSQL, which natively supports the jsonb data type. By adding this annotation to the corresponding attribute in our entity class, we provide a hint to the database about the desired column type. Spring Data JPA typically auto-detects the jsonb data type based on the database column definition, making this annotation optional in many cases.

4. Setting up Project Dependencies and Test Data

We’ll create a basic Spring Boot project with the necessary dependencies and test data for testing the JSONB queries.

4.1. Project Setup

First, we need to add the necessary dependencies to our Maven pom.xml file:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

4.2. Entity Class

Next, let’s create a Java class named Product to represent our entity:

public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    @Column(columnDefinition = "jsonb")
    private String attributes;
    // Getters and Setters 
}

This class defines the Product entity with id, name, and attributes fields. The attributes field is a String that will hold the serialized JSON data for product details. We use @Column(columnDefinition = “jsonb”) to hint the database to create an attributes column as a JSONB type.

After defining the Product entity class, Hibernate will generate the following SQL when the application starts up and initializes the database schema:

CREATE TABLE Product (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name VARCHAR(255),
    attributes JSONB
);

4.3. Prepare Test Data

Below is the SQL script that we use to prepare our database before running the test cases. We can save this script in a .sql file and place it inside the src/test/resources directory of our project:

DELETE FROM product;
INSERT INTO product (name, attributes)
VALUES ('Laptop', '{"color": "red", "size": "15 inch"}');
INSERT INTO product (name, attributes)
VALUES ('Phone', '{"color": "blue", "size": "6 inch"}');
INSERT INTO product (name, attributes)
VALUES ('Headphones', '{"brand": "Sony", "details": {"category": "electronics", "model": "WH-1000XM4"}}');
INSERT INTO product (name, attributes)
VALUES ('Laptop', '{"brand": "Dell", "details": {"category": "computers", "model": "XPS 13"}}');

Then, we use the @Sql annotation with the executionPhase attribute set to BEFORE_TEST_METHOD in the test class to insert test data into the database before each test method execution:

@Sql(scripts = "/testdata.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD)

5. Using Native Queries with @Query

In this section, we’ll leverage native SQL queries with PostgreSQL JSONB operators to filter and retrieve data based on values within the JSONB column. We use the @Query annotation to define these native queries within our Spring Data JPA repository interface.

5.1. Querying with JSONB Operators

The @Query annotation allows us to define custom queries within our repository interface using native SQL syntax. This approach is particularly useful when working with JSONB columns, as it enables us to utilize PostgreSQL’s native JSONB operators directly within the query.

Let’s write a query using JSONB operators to find all products with a specific color value:

public interface ProductRepository extends JpaRepository<Product, Long> {
    @Query(value = "SELECT * FROM product WHERE attributes ->> ?1 = ?2", nativeQuery = true)
    List<Product> findByAttribute(String key, String value);
}

The findByAttribute() method takes in two arguments representing the key of the JSON attribute (such as “color”) and filters by a value indicating the desired value for that attribute. The @Query annotation defines a native SQL query that utilizes the ->> operator to access the key within the attributes JSONB column.

Then, the placeholders ?1 and ?2 in the query are replaced with the actual name of the key and value provided as method arguments during execution. Next, let’s create a test case to verify the functionality of the findByAttribute() method:

List<Product> redProducts = productRepository.findByAttribute("color", "red");
assertEquals(1, redProducts.size());
assertEquals("Laptop", redProducts.get(0).getName());

5.2. Querying Nested with JSONB Operators

We’re utilizing PostgreSQL’s -> and ->> operators to query nested JSONB data:

• The -> operator is used to access a specific key within a JSONB object.
• The ->> operator is used to access the value corresponding to a specific key within a JSONB object as text.

Let’s write another query for handling nested keys:

@Query(value = "SELECT * FROM product WHERE attributes -> ?1 ->> ?2 = ?3", nativeQuery = true)
List<Product> findByNestedAttribute(String key1, String key2, String value);

This query allows us to search for entities where a specific nested attribute matches a given value. For example, if we want to find products where the “details.category” is “electronics”, we’d call this method with “details”, “category”, and “electronics“ as parameters:

List<Product> electronicProducts = productRepository.findByNestedAttribute("details", "category", "electronics");
assertEquals(1, electronicProducts.size());
assertEquals("Headphones", electronicProducts.get(0).getName());

5.3. Querying with jsonb_extract_path_text Functions

We can also leverage the jsonb_extract_path_text function in our native SQL queries to extract specific values from JSONB data. jsonb_extract_path_text is a PostgreSQL function used to extract a specific value from a JSONB column based on a given path.

The jsonb_extract_path_text function returns the extracted value as text. If the specified path doesn’t exist in the JSONB structure, the function returns NULL.

Let’s see an example of using jsonb_extract_path_text:

public interface ProductRepository extends JpaRepository<Product, Long> {
    @Query(value = "SELECT * FROM product WHERE jsonb_extract_path_text(attributes, ?1) = ?2", nativeQuery = true)
    List<Product> findByJsonPath(String path, String value);
}

The findByJsonPath() method accepts two arguments. The first argument is the path string indicating the specific key within the JSONB object to extract. The second argument represents the expected value for the extracted attribute:

List<Product> redProducts = productRepository.findByJsonPath("color", "red");
assertEquals(1, redProducts.size());
assertEquals("Laptop", redProducts.get(0).getName());

5.4. Querying Nested with jsonb_extract_path_text Functions

Let’s see how we can adjust the query to handle nested keys using jsonb_extract_path_text functions:

@Query(value = "SELECT * FROM product WHERE jsonb_extract_path_text(attributes, ?1, ?2) = ?3", nativeQuery = true)
List<Product> findByNestedJsonPath(String key1, String key2, String value);

We provide key1 and key2 as path elements to traverse the nested JSONB structure:

List<Product> electronicProducts = productService.findByNestedJsonPath("details", "category", "electronics");
assertEquals(1, electronicProducts.size());
assertEquals("Headphones", electronicProducts.get(0).getName());

In this example, the findByNestedJsonPath(“details”, “category”, “electronics”) would target products where the nested “details.category” value is “electronics“.

6. Using Custom JPA Specification Approach

JPA Specifications are interfaces that encapsulate the criteria used for filtering data. They define what data needs to be retrieved based on specific conditions. This interface, provided by Spring Data JPA, allows repositories to implement custom query methods that accept a Specification<T> instance as an argument.

We can create a class that implements the Specification<T> interface. This class defines the toPredicate() method, which utilizes the CriteriaBuilder to construct the actual query predicate based on the provided criteria (key and value for filtering):

public class ProductSpecification implements Specification<Product> {
    private final String key;
    private final String value;
    public ProductSpecification(String key, String value) {
        this.key = key;
        this.value = value;
    }
    @Override
    public Predicate toPredicate(Root root, CriteriaQuery<?> query, CriteriaBuilder cb) {
        return cb.equal(
            cb.function("jsonb_extract_path_text", String.class, root.get("attributes"), cb.literal(key)),
            value
        );
    }
}

The toPredicate() method defines how the filtering predicate is constructed using the CriteriaBuilder provided as an argument. In this example, we’re assuming the key is located at the top level of the JSONB data.

To use this custom specification, the ProductRepository needs to extend JpaSpecificationExecutor<Product>:

public interface ProductRepository extends JpaRepository<Product, Long>, JpaSpecificationExecutor<Product> {
}

Here’s a basic example of a custom specification for filtering products based on attributes within the JSONB column:

ProductSpecification spec = new ProductSpecification("color", "red");
Page<Product> redProducts = productRepository.findAll(spec, Pageable.unpaged());
assertEquals(1, redProducts.getContent().size());
assertEquals("Laptop", redProducts.getContent().get(0).getName());

7. Conclusion

In this article, we explored various approaches for querying JSONB columns using Spring Data JPA. For basic filtering criteria, native SQL queries might offer a straightforward solution. However, the JPA specification provides a compelling alternative when dealing with complex filtering logic or the need for reusability.

As always, the source code for the examples is available over on GitHub.