Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/spring-data-search/spring-boot-starter-data-search
Spring-Data search API augmented with Natural Language support.
https://github.com/spring-data-search/spring-boot-starter-data-search
antlr4 java jpa mongodb spring spring-boot spring-boot-starter-data-search spring-data spring-data-jpa spring-data-mongodb
Last synced: about 15 hours ago
JSON representation
Spring-Data search API augmented with Natural Language support.
- Host: GitHub
- URL: https://github.com/spring-data-search/spring-boot-starter-data-search
- Owner: spring-data-search
- License: apache-2.0
- Created: 2021-09-23T20:09:23.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-03-07T20:10:04.000Z (almost 2 years ago)
- Last Synced: 2024-11-13T15:56:58.509Z (3 months ago)
- Topics: antlr4, java, jpa, mongodb, spring, spring-boot, spring-boot-starter-data-search, spring-data, spring-data-jpa, spring-data-mongodb
- Language: Java
- Homepage: https://github.com/spring-data-search
- Size: 479 KB
- Stars: 7
- Watchers: 1
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
[](https://github.com/commerce-io/spring-boot-starter-data-search/actions/workflows/build.yml)
[](https://sonarcloud.io/summary/new_code?id=commerce-io_spring-boot-starter-data-search)
[](https://sonarcloud.io/summary/new_code?id=commerce-io_spring-boot-starter-data-search)
[](https://sonarcloud.io/summary/new_code?id=commerce-io_spring-boot-starter-data-search)
[](https://sonarcloud.io/summary/new_code?id=commerce-io_spring-boot-starter-data-search)
[](https://sonarcloud.io/summary/new_code?id=commerce-io_spring-boot-starter-data-search)
[](https://sonarcloud.io/summary/new_code?id=commerce-io_spring-boot-starter-data-search)
spring-boot-starter-data-search
Spring Data Search API augmented with Natural Language support.
Already supported:
Data Search is compatible with
Spring Native
(see the list of supported drivers and limitations)
Coming soon:
Demo:
spring-boot-starter-data-search-mongodb-demo
spring-boot-starter-data-search-jpa-demo
# Table of Contents
- [Data Search](#data-search)
- [Features](#features)
- [Comparison operators](#comparison-operators)
- [Supported values](#supported-values)
- [Detailed use case](#detailed-use-case)
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Demo](#demo)
- [Mongodb demo](#mongodb-demo)
- [JPA demo](#jpa-demo)
- [Installation](#installation)
- [Data Search Mongodb starter](#data-search-mongodb-starter)
- [Data Search JPA Starter](#data-search-jpa-starter)
- [Configuration](#configuration)
- [Mongodb Repository](#mongodb-repository)
- [JPA Repository](#jpa-repository)
- [Usage](#usage)
- [Field Mapping](#field-mapping)
- [Flat Mapper](#flat-mapper)
- [Advanced Mapper](#advanced-mapper)
- [Value Mapping](#value-mapping)
- [Contributors](#Contributors)
- [License](#license)
# Data Search
Data Search provides an enterprise & production ready API, prowered by Spring Boot and Antlr, to query your data, and perform advanced search with Natural Language.
**Search example**: users born after 1988-01-01, with an gmail or protonmail email address, having completed the email verification, and having an address in one of the following countries: France, Switzerland or China
`birthDate >: '1988-01-01' and (emailAddress : *gmail.com or emailAddress: *protonmail.com) and emailAddressVerified: true and addresses.countryCode: 'FR,CH,CN'`
# Features
- Logical operators (or/ and)
- Parenthesis/ criteria prioritization
- Mongodb and all JPA compatible db engines
- Fields mapping/ DTO to Entities
- Filter by subentity fields/ deep search
- Advanced RegEx for Mongodb and like operator for JPA
- All comparison operators
## Comparison operators
#### Equal :
`emailAddressVerified : true`
#### Not equal !:
`emailAddressVerified !: true`
#### In :
`countryCode : 'FR,CH,CN'`
#### Not in :
`countryCode !: 'FR,CH,CN'`
#### Starts with :
`firstName: S*`
#### Ends with :
`firstName: *S`
#### Contains :
`firstName: *S*`
#### Less than <
`birthDate < '1988-01-01'`
#### Less than or equal <:
`birthDate <: '1988-01-01'`
#### Greater than >
`birthDate > '1988-01-01'`
#### Greater than or equal >:
`birthDate >: '1988-01-01'`
#### Exists (is not null)
`birthDate`
#### Doesn't exist (is null) !
`!birthDate`
## Supported values
#### String
`firstName : Stan`
#### Enum
`title : MR`
#### Boolean
`emailAddressVerified : true`
#### Number (Integer, Double, Long, BigDecimal)
`ref >: 100 or coins > 6.76453`
#### LocalTime
`time >: '18:58:24' and time <: '18:58:24.999'`
#### OffsetTime
`time >: '18:58:24Z' and time <: '20:58:24.999+02:00'`
#### LocalDate
`birthDate >: '1988-01-01'`
#### LocalDateTime
`createdDate >: '2021-08-23T18:58:24' and createdDate <: '2021-10-12T18:58:24.000'`
#### OffsetDateTime
`createdDate >: "2021-08-23T18:58:24Z" and createdDate <: '2021-10-12T18:58:24.000+02:00'`
#### Array
`countryCode : 'FR,CH,CN'`
#### RegEx
`emailAddress : '/.*gmail.com/'`
Regular expression, supported only for mongodb ([see documentation](https://docs.mongodb.com/manual/reference/operator/query/regex/)) |
# Detailed use case
See detailed search use case [here](./docs/use-cases.md)
# Getting Started
## Requirements
**Java version** 11 or higher (_If java 8 support is needed, please vote
for [this issue](https://github.com/commerce-io/spring-boot-starter-data-search/issues/3)_)
**SpringBoot version** 2.1.0 or higher
## Demo
### Mongodb demo
https://github.com/commerce-io/spring-boot-starter-data-search-mongodb-demo
### JPA demo
https://github.com/commerce-io/spring-boot-starter-data-search-jpa-demo
## Installation
:arrow_right: [Get the latest releases here](https://github.com/commerce-io/spring-boot-starter-data-search/releases) :arrow_left:
#### Data Search Mongodb starter
**Maven**
```xml
app.commerce-io
spring-boot-starter-data-search-mongodb
1.3.0
```
**Gradle**
`implementation 'app.commerce-io:spring-boot-starter-data-search-mongodb:1.3.0'`
#### Data Search JPA Starter
**Maven**
```xml
app.commerce-io
spring-boot-starter-data-search-jpa
1.3.0
```
**Gradle**
`implementation 'app.commerce-io:spring-boot-starter-data-search-jpa:1.3.0'`
## Configuration
Data Search provides a custom repository. In order to use the provided repository, add the following annotation to the main class or any other
configuration class.
### Mongodb Repository
```java
@Configuration
@EnableMongoRepositories(repositoryBaseClass = SearchRepositoryImpl.class)
public class DemoConfiguration {
}
```
### JPA Repository
```java
@Configuration
@EnableJpaRepositories(repositoryBaseClass = SearchRepositoryImpl.class)
public class DemoConfiguration {
}
```
## Usage
Make your repositories extend `SearchRepository`
```java
@Repository
public interface CustomerRepository extends SearchRepository {
}
```
And use in a controller or from anywhere else
```java
@RestController
@RequiredArgsConstructor
public class DemoController {
private final CustomerRepository customerRepository;
@Transactional(readOnly = true)
@RequestMapping(
method = RequestMethod.GET,
value = "/customers",
produces = {"application/json"}
)
public ResponseEntity> searchCustomers(
@RequestParam(value = "search", required = false) String search,
Pageable pageable) {
Page customerPage = customerRepository.findAll(
search,
pageable);
return ok(customerPage);
}
}
```
## Field Mapping
Users will tend to filter by the search result fields, and sometimes, your DTO structure differs from your entity/ collection.
Data search provides a mapper, to define your custom mappings rules in two different ways:
### Flat Mapper
The flat mapper is a basic String to String mapping, which could be useful for simple use cases.
```java
String search = "addressName: test";
Mapper addressMapper = Mapper.flatMapper()
.mapping("addressName", "address.firstName")
.build();
Page page = customerRepository.findAll(search, pageable, addressMapper);
```
### Advanced Mapper
The advanced mapper is used for complex structure mapping, and enable the reuse of mappers. Advanced mappers can be combined with flat mappers.
```java
String search = "name: test OR address.addressName: test";
Mapper addressMapper = Mapper.flatMapper()
.mapping("addressName", "firstName")
.build();
Mapper mapper = Mapper.mapper()
.mapping("name", "firstName")
.mapping("address", "addressEntity", addressMapper)
.build();
Page page = customerRepository.findAll(search, pageable, mapper);
```
## Value Mapping
In addition to the fields mapping, some values could be converted before returning the search result.
Data Search supports values mapping:
```java
public class LowerCaseValueMapping implements ValueMapping {
@Override
public String map(String from) {
return from == null ? null : from.toLowerCase();
}
}
```
```java
String search = "addressName: TeSt";
Mapper addressMapper = Mapper.flatMapper()
.mapping("addressName", "address.firstName", new LowerCaseValueMapping())
.build();
Page page = customerRepository.findAll(search, pageable, addressMapper);
```
# Contributors
[](#contributors)
Thanks to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@adlmez
💻 🤔 👀 💡 ⚠️
Dependabot
🚇
All Contributors
🚇
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
# License
[](https://github.com/commerce-io/spring-boot-starter-data-search/blob/main/LICENSE.txt)
This software is released under the Apache license. See `LICENSE` for more information.
[license-shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg
[license-url]: https://github.com/commerce-io/spring-boot-starter-data-search/blob/main/LICENSE.txt
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!