rsql-jpa-specification

The library supports querying PostgreSQL jsonb fields using dot notation to traverse the JSON structure. It utilizes the PostgreSQL jsonb_path_exists function under the hood.

Supported JSON primitive types:

• string
• number
• boolean
• array

Temporal Values: Since PostgreSQL 13, jsonb supports temporal values via the datetime() function. When querying date-time values stored in JSONB, you must use the ISO 8601 format. If the request conforms to a timezone pattern, the library will use jsonb_path_exists_tz.

// Example: querying a nested field in a jsonb column named 'data'
String rsql = "data.user.id==1";
List<User> users = userRepository.findAll(toSpecification(rsql));

For your JPA repository to support RSQL-based queries, it must extend both JpaSpecificationExecutor (for Spring Data JPA Specifications) and QuerydslPredicateExecutor (for QueryDSL Predicates).

package com.perplexhub.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import org.springframework.data.querydsl.QuerydslPredicateExecutor;

import com.perplexhub.model.User;

public interface UserRepository extends JpaRepository<User, String>, JpaSpecificationExecutor<User>, QuerydslPredicateExecutor<User> {
}

To translate RSQL queries into Spring Data JPA Specification objects, add the rsql-jpa-spring-boot-starter dependency to your Maven project.

Compatibility Note:

• SpringBoot 4+: Use version 7.x or higher.
• SpringBoot 3: Use version 6.x.
• SpringBoot 2: Use version 5.x.

<dependency>
  <groupId>io.github.perplexhub</groupId>
  <artifactId>rsql-jpa-spring-boot-starter</artifactId>
  <version>X.X.X</version>
</dependency>

To enable RSQL support within your Spring application context, import the RSQLConfig class using the @Import annotation.

@Import(io.github.perplexhub.rsql.RSQLConfig.class)

To enable RSQL to QueryDSL translation, your repository interface must extend QuerydslPredicateExecutor (alongside JpaRepository and JpaSpecificationExecutor).

package com.perplexhub.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import org.springframework.data.querydsl.QuerydslPredicateExecutor;
import com.perplexhub.model.User;

public interface UserRepository extends JpaRepository<User, String>, JpaSpecificationExecutor<User>, QuerydslPredicateExecutor<User> {
}

To enable RSQL support in your JPA repositories, your repository interface must extend JpaSpecificationExecutor.

Example implementation:

public interface UserRepository extends JpaRepository<User, String>, JpaSpecificationExecutor<User> {
}

package com.perplexhub.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import com.perplexhub.model.User;

public interface UserRepository extends JpaRepository<User, String>, JpaSpecificationExecutor<User> {
}

To use this library, you must include spring-data-jpa in your Maven configuration. If you intend to use RSQLSupport.toPredicate for QueryDSL translation, you must also include querydsl-core.

<!-- Add spring-data-jpa to your pom.xml -->
<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-jpa</artifactId>
  <version>x.y.z</version>
</dependency>

<!-- Add querydsl-core to your pom.xml if you plan to use RSQLSupport.toPredicate -->
<dependency>
  <groupId>com.querydsl</groupId>
  <artifactId>querydsl-core</artifactId>
  <version>x.y.z</version>
</dependency>

To translate RSQL queries into QueryDSL Predicate objects, add the rsql-querydsl-spring-boot-starter dependency.

Configuration: Your repository interface must extend both JpaSpecificationExecutor and QuerydslPredicateExecutor to support both translation types.

<dependency>
  <groupId>io.github.perplexhub</groupId>
  <artifactId>rsql-querydsl-spring-boot-starter</artifactId>
  <version>X.X.X</version>
</dependency>

When using the LIKE operator in RSQL, you may need to escape special characters (like % or _) to search for them literally. To do this, use QuerySupport.builder() to specify a likeEscapeCharacter.

Example: To search for a string containing an underscore (_) using $ as the escape character, your RSQL query should look like name=like='$_' and you must configure the builder with the escape character.

char escapeChar = '$';
QuerySupport query = QuerySupport.builder()
    .rsqlQuery("name=like='" + escapeChar + "%'")
    .likeEscapeCharacter(escapeChar)
    .build();
List<Company> users = companyRepository.findAll(toSpecification(query));

Use RSQLSupport.toPredicate(filter, path) to convert an RSQL string into a QueryDSL Predicate (specifically a BooleanExpression). This requires a QueryDSL generated path object (e.g., QUser.user).

Features:

• Pagination: Pass a Pageable object to findAll.
• Property Path Remapping: Use a Map<String, String> to map external RSQL property names to your internal domain model paths.

// Basic usage with QueryDSL path
repository.findAll(RSQLSupport.toPredicate(filter, QUser.user));

// With pagination
Pageable pageable = PageRequest.of(0, 5);
repository.findAll(RSQLSupport.toPredicate(filter, QUser.user), pageable);

// With property path remapping
Map<String, String> propertyPathMapper = new HashMap<>();
propertyPathMapper.put("compId", "company.id");
repository.findAll(RSQLSupport.toPredicate(filter, QUser.user, propertyPathMapper));

To generate QueryDSL BooleanExpression objects, use RSQLSupport.toPredicate(filter, path).

Features:

• Path Mapping: Supports remapping property paths via a Map.
• Per-query Conversion: You can provide a specific Spring ConversionService for a single query using the four-argument overload.

// Basic usage with QueryDSL path
repository.findAll(RSQLSupport.toPredicate(filter, QUser.user));

// With property path remapping
Map<String, String> propertyPathMapper = new HashMap<>();
propertyPathMapper.put("compId", "company.id");
repository.findAll(toPredicate(filter, QUser.user, propertyPathMapper));

// With a specific ConversionService
repository.findAll(toPredicate(filter, QUser.user, propertyPathMapper, applicationConversionService));