Need a way to dynamically filter entities without effort? With Spring Filter, your API will gain a full-featured search functionality. If you don't have a web API, you may still use the powerful filter builder in order to generate complex SQL or Mongo queries.
Since the library is very modular and well integrated with Spring, you can add custom operators and functions, or even bring support to a different platform. JavaScript filter builders are also available so that it's not a headache anymore to generate valid queries in frontend applications.
⚠️ About Release 3.0.0
Spring Filter 3.0.0 is a new release built from the group up. It includes much better integration with Spring, with many new features, enhancements and bug fixes. The language syntax didn't change, frontend applications will therefore not require any modification. The new
FilterBuilderclass is incompatible with the previous one and other breaking changes are present but the basic usage of the library remains similar. Please feel free to create an issue if you notice anything wrong. Consider supporting the project by sponsoring us.
You can access the older version in the 2.x.x branch.
Example (try it live)
/search?filter= average(ratings) > 4.5 and brand.name in ['audi', 'land rover'] and (year > 2018 or km < 50000) and color : 'white' and accidents is empty
/* Entity used in the query above */
@Entity public class Car {
@Id long id;
int year;
int km;
@Enumerated Color color;
@ManyToOne Brand brand;
@OneToMany List<Accident> accidents;
@ElementCollection List<Integer> ratings;
// ...
}🚀 Yes we support booleans, dates, enums, functions, and even relations! Need something else? Tell us here.
 |
<dependency>
<groupId>com.turkraft.springfilter</groupId>
<artifactId>jpa</artifactId>
<version>3.0.7</version>
</dependency>@GetMapping(value = "/search")
Page<Entity> search(@Filter Specification<Entity> spec, Pageable page) {
return repository.findAll(spec, page);
}The repository should implement JpaSpecificationExecutor in order to execute Spring's Specification, SimpleJpaRepository is a well known implementation. You can remove the Pageable argument and return a List if pagination and sorting are not needed.
<dependency>
<groupId>com.turkraft.springfilter</groupId>
<artifactId>mongo</artifactId>
<version>3.0.7</version>
</dependency>@GetMapping(value = "/search")
Page<Entity> search(@Filter(entityClass = Entity.class) Query query, Pageable page) {
return mongoTemplate.find(query.with(pageable), Entity.class);
}<dependency>
<groupId>com.turkraft.springfilter</groupId>
<artifactId>core</artifactId>
<version>3.0.7</version>
</dependency>@Autowired FilterBuilder fb;
FilterNode filter = fb.field("year").equal(fb.input(2023)).and(fb.isNull(fb.field("category"))).get();
@Autowired ConversionService cs;
String query = cs.convert(filter, String.class); // year : 2023 and category is nullPlease note that Spring's ConversionService is internally used when converting objects to strings and vice-versa.
Spring Filter does not enforce any pattern for dates and other types.
Customization should be done directly within Spring if required.
Instead of manually writing string queries in your frontend applications, you may use the JavaScript query builder.
import {SpringFilterQueryBuilder as builder} from 'https://cdn.jsdelivr.net/npm/spring-filter-query-builder@0.3.0/src/index.min.js';
const filter =
builder.or(
builder.and(
builder.equal("test.test1", "testvalue1"),
builder.isNotNull("test.test2")
),
builder.notEqual("test.test2", "testvalue2")
);
const req = await fetch('http://api/person?filter=' + filter.toString());Please see documentation.
field, field.nestedField
123, -321.123, true, false, 'hello world', 'escape \' quote', '1-01-2023'
[1, 2, 3], [field, ['x', 'y'], 99]
f(), f(x), f(x, y)
`place_holder`
x and (y or z)
op expr, not ready
expr op expr, x and y
expr op, field is null
Below are listed the operators and functions which are supported by all integrations (JPA and Mongo). Integrations may extend this common language.
| Literal | Description | Example |
|---|---|---|
| and | and's two expressions | status : 'active' and createdAt > '1-1-2000' |
| or | or's two expressions | value ~ '*hello*' or name ~ '*world*' |
| not | not's an expression | not (id > 100 or category.order is null) |
| Literal | Description | Example |
|---|---|---|
| ~ | checks if the left (string) expression is similar to the right (string) expression | catalog.name ~ '*electronic*' |
| ~~ | similar to the previous operator but case insensitive | catalog.name ~~ 'ElEcTroNic*' |
| : | checks if the left expression is equal to the right expression | id : 5 |
| ! | checks if the left expression is not equal to the right expression | username ! 'torshid' |
| > | checks if the left expression is greater than the right expression | distance > 100 |
| >: | checks if the left expression is greater or equal to the right expression | distance >: 100 |
| < | checks if the left expression is smaller than the right expression | distance < 100 |
| <: | checks if the left expression is smaller or equal to the right expression | distance <: 100 |
| is null | checks if an expression is null | status is null |
| is not null | checks if an expression is not null | status is not null |
| is empty | checks if the (collection) expression is empty | children is empty |
| is not empty | checks if the (collection) expression is not empty | children is not empty |
| in | checks if an expression is present in the right expressions | status in ['initialized', 'active'] |
| not in | checks if an expression is not present in the right expressions | status not in ['failed', 'closed'] |
| Name | Description | Example |
|---|---|---|
| size | returns the collection's size | size(accidents) |
Ideas and pull requests are always welcome. Google's Java Style is used for formatting.
- Thanks to @marcopag90 and @glodepa for adding support to MongoDB.
- Thanks to @sisimomo for creating the JavaScript query builder.
- Thanks to @68ociredef for creating the Angular query builder.
Distributed under the MIT license.