Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ajclopez/mongo-spring-search
Convert URL query parameters to MongoDB queries
https://github.com/ajclopez/mongo-spring-search
api mongodb mongodb-database mongodb-query mongodb-query-language query query-builder querystring spring-boot-mongodb springboot url
Last synced: 1 day ago
JSON representation
Convert URL query parameters to MongoDB queries
- Host: GitHub
- URL: https://github.com/ajclopez/mongo-spring-search
- Owner: ajclopez
- License: mit
- Created: 2021-01-07T04:20:48.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-07-21T15:31:08.000Z (2 months ago)
- Last Synced: 2024-09-23T01:32:15.681Z (5 days ago)
- Topics: api, mongodb, mongodb-database, mongodb-query, mongodb-query-language, query, query-builder, querystring, spring-boot-mongodb, springboot, url
- Language: Java
- Homepage:
- Size: 42 KB
- Stars: 10
- Watchers: 3
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[![MIT License][license-shield]][license-url]
[](https://search.maven.org/search?q=g:%22io.github.ajclopez%22%20AND%20a:%22mongo-spring-search%22)
[](https://codecov.io/gh/ajclopez/mongo-spring-search)
Mongo Spring Search
Mongo Spring Search provides a query language to a MongoDB database.
Explore the docs
Report Bug
·
Request Feature
# Mongo Spring Search
### Content index
* [What is this?](#what-is-this)
* [Getting Started](#getting-started)
* [Installation](#installation)
* [Usage](#usage)
* [Supported features](#supported-features)
* [Filtering](#filtering)
* [Pagination](#pagination)
* [Sorting](#sorting)
* [Projection](#projection)
* [Advanced queries](#advanced-queries)
* [Available options](#available-options)
* [Customize limit value](#customize-limit-value)
* [Specify casting per param keys](#specify-casting-per-param-keys)
* [Contributing](#contributing)
* [License](#license)
## What is this?
Mongo Spring Search provides a simple query language to perform advanced searches for your collections in **MongoDB**.
You could create custom repository methods to perform your searches. You could also use **Mongo Spring Search** to searching, sorting, pagination and combining logical operators.
## Getting Started
### Installation
##### Maven
Include the dependency to your project inside your `pom.xml` file.
For Java 17:
```xml
io.github.ajclopez
mongo-spring-search
2.0.1
```
For Java 14:
```xml
io.github.ajclopez
mongo-spring-search
1.0.5
```
##### Gradle
Add implementation to your project in your `build.gradle` file
For Java 17:
```
implementation 'io.github.ajclopez:mongo-spring-search:2.0.1'
````
For Java 14:
```
implementation 'io.github.ajclopez:mongo-spring-search:1.0.5'
````
#### Note
- **Version 2.x.x:** Requires Java 17.
- **Version 1.x.x:** Requires Java 14.
## Usage
Converts query into a MongoDB query object.
```java
MongoSpringSearch.mss(String query);
MongoSpringSearch.mss(String query, Optional configuration);
```
##### Arguments
`query`: query string part of the requested API URL.
`configuration`: object for advanced configuration (See below) [optional].
You can add custom methods to your repository:
```java
@Repository
public interface YourRepository extends MongoRepository, YourCustomRepository {
}
```
To expand the `Spring MongoRepository` repository methods you can do it in the following way:
```java
public interface YourCustomRepository {
public List findAll(String query);
}
```
In this class you can use `Mongo Spring Search`:
```java
public class YourCustomRepositoryImpl implements YourCustomRepository {
private MongoTemplate mongoTemplate;
@Autowired
public YourCustomRepositoryImpl(MongoTemplate mongoTemplate) {
this.mongoTemplate = mongoTemplate;
}
@Override
public List findAll(String query) {
return mongoTemplate.find(MongoSpringSearch.mss(query), YourDocument.class);
}
}
```
Use it in your controller:
```java
@GetMapping
public ResponseEntity> yourFunctionNameHere(HttpServletRequest request) {
return ResponseEntity.ok().body(yourRepository.findAll(request.getQueryString()));
}
```
##### Example
```java
Query query = MongoSpringSearch.mss("status=sent&date>2020-01-06T14:00:00.000Z&author.firstname=Jhon&skip=50&limit=100&sort=-date&fields=id,date");
```
## Supported features
### Filtering
| Operator | URI | Example |
| ----------------- | --------------------- | --------------------------------- |
| `$eq` | `key=val` | `type=public` |
| `$ne` | `key!=val` | `status!=SENT` |
| `$gt` | `key>val` | `price>5` |
| `$gte` | `key>=val` | `price>=9` |
| `$lt` | `key` | `email=/@gmail\.com$/` |
| `$regex` | `key!=/value/` | `phone!=/^58/` |
### Pagination
Useful to limit the number of records returned.
- Operator keys are `skip` and `limit`.
- Use `limit` operator to limit the number of records returned.
- Use `skip` operator to skip the specified number of records.
```json
skip=20&limit=10
```
### Sorting
Useful to sort returned records.
- Operator key is `sort`.
- It accepts a comma-separated list of fields.
- Use `-` prefixes to sort in descending order.
- Use `+` prefixes to sort in ascedending order.
```json
sort=id,-date
```
### Projection
Useful to limit fields to return in each records.
- Operator key is `fields`.
- It accepts a comma-separated list of fields.
```json
fields=firstname,lastname,phone,email
```
**Note:**
* The `_id` field (returned by default).
### Advanced queries
For more advanced usage (`and`, `or` logic operations), pass query `filter` as string with the logical operations, for example:
```json
filter=(country=Mexico OR country=Spain) and gender=female
````
##### What operations are possible?
* Filtering operations.
* The `AND/and` operator.
* The `OR/or` operator.
* Parenthesis can be used for grouping.
## Available options
You can use advanced options:
```java
Configuration(Map casters, Integer defaultLimit, Integer maxLimit)
```
* `casters` object to specify custom casters, key is the caster name, and value is a type (`BOOLEAN, NUMBER, PATTERN, DATE, STRING`).
* `defaultLimit` which contains custom value to return records.
* `maxLimit` which contains custom value to return a maximum of records.
### Customize limit value
You can specify your own maximum or default limit value.
* `defaultLimit`: custom value to return records.
* `maxLimit`: custom value to return a maximum of records.
```java
Configuration options = new Configuration(null, 10, 500);
MongoSpringSearch.mss("organizationId=123&skip=10&limit=1000", Optional.of(options));
```
### Specify casting per param keys
You can specify how query parameter values are casted by passing an object.
* `casters`: object which map keys to casters.
```java
Map casters = new HashMap();
casters.put("key1", CastType.STRING);
casters.put("key2", CastType.NUMBER);
casters.put("key3", CastType.STRING);
casters.put("key4", CastType.OBJECT_ID);
casters.put("key5", CastType.BOOLEAN);
Configuration options = new Configuration(casters, null, null);
MongoSpringSearch.mss("key1=VALUE&key2=10&key3=20&key4=666fde1af688038e64d6b58a&key5=true", Optional.of(options));
```
## Contributing
Should you like to provide any feedback, please open up an Issue, I appreciate feedback and comments. Any contributions you make are **greatly appreciated**.
1. Fork the Project
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing-feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This software is released under the MIT license. See `LICENSE` for more information.
[license-shield]: https://img.shields.io/badge/License-MIT-yellow.svg
[license-url]: https://github.com/ajclopez/mongo-spring-search/blob/master/LICENSE.txt