{"id":15154331,"url":"https://github.com/ajclopez/mongo-spring-search","last_synced_at":"2025-10-24T10:30:57.140Z","repository":{"id":57732292,"uuid":"327501470","full_name":"ajclopez/mongo-spring-search","owner":"ajclopez","description":"Convert URL query parameters to MongoDB queries","archived":false,"fork":false,"pushed_at":"2024-07-21T15:31:08.000Z","size":43,"stargazers_count":11,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-29T09:51:15.494Z","etag":null,"topics":["api","mongodb","mongodb-database","mongodb-query","mongodb-query-language","query","query-builder","querystring","spring-boot-mongodb","springboot","url"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajclopez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-07T04:20:48.000Z","updated_at":"2024-10-31T01:30:28.000Z","dependencies_parsed_at":"2024-06-05T04:33:13.774Z","dependency_job_id":"6c664544-fae1-41a7-a439-c95df58e7195","html_url":"https://github.com/ajclopez/mongo-spring-search","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajclopez%2Fmongo-spring-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajclopez%2Fmongo-spring-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajclopez%2Fmongo-spring-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajclopez%2Fmongo-spring-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajclopez","download_url":"https://codeload.github.com/ajclopez/mongo-spring-search/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237950826,"owners_count":19392666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","mongodb","mongodb-database","mongodb-query","mongodb-query-language","query","query-builder","querystring","spring-boot-mongodb","springboot","url"],"created_at":"2024-09-26T17:21:49.374Z","updated_at":"2025-10-24T10:30:56.793Z","avatar_url":"https://github.com/ajclopez.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MIT License][license-shield]][license-url]\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.ajclopez/mongo-spring-search.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22io.github.ajclopez%22%20AND%20a:%22mongo-spring-search%22)\n[![codecov](https://codecov.io/gh/ajclopez/mongo-spring-search/branch/master/graph/badge.svg?token=CY5KSHCCG0)](https://codecov.io/gh/ajclopez/mongo-spring-search)\n\n\u003cp align=\"center\"\u003e\n  \u003ch3 align=\"center\"\u003eMongo Spring Search\u003c/h3\u003e\n  \u003cp align=\"center\"\u003e\n    Mongo Spring Search provides a query language to a MongoDB database.\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/ajclopez/mongo-spring-search#usage\"\u003e\u003cstrong\u003eExplore the docs\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/ajclopez/mongo-spring-search/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/ajclopez/mongo-spring-search/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n# Mongo Spring Search\n\n\n\n### Content index\n\n* [What is this?](#what-is-this)\n* [Getting Started](#getting-started)\n    *  [Installation](#installation)\n* [Usage](#usage)\n* [Supported features](#supported-features)\n    * [Filtering](#filtering)\n    * [Pagination](#pagination)\n    * [Sorting](#sorting)\n    * [Projection](#projection)\n    * [Advanced queries](#advanced-queries)\n* [Available options](#available-options)\n    * [Customize limit value](#customize-limit-value)\n    * [Specify casting per param keys](#specify-casting-per-param-keys)\n* [Contributing](#contributing)\n* [License](#license)\n\n## What is this?\n\nMongo Spring Search provides a simple query language to perform advanced searches for your collections in **MongoDB**.\n\nYou could create custom repository methods to perform your searches. You could also use **Mongo Spring Search** to searching, sorting, pagination and combining logical operators.\n\n## Getting Started\n\n### Installation\n\n##### Maven\n\nInclude the dependency to your project inside your `pom.xml` file. \n\nFor Java 17:\n```xml  \n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.ajclopez\u003c/groupId\u003e\n  \u003cartifactId\u003emongo-spring-search\u003c/artifactId\u003e\n  \u003cversion\u003e2.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nFor Java 14:\n```xml  \n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.ajclopez\u003c/groupId\u003e\n  \u003cartifactId\u003emongo-spring-search\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.5\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n##### Gradle\n\nAdd implementation to your project in your `build.gradle` file\n\nFor Java 17:\n```\nimplementation 'io.github.ajclopez:mongo-spring-search:2.0.1'\n````\n\nFor Java 14:\n```\nimplementation 'io.github.ajclopez:mongo-spring-search:1.0.5'\n````\n\n#### Note\n- **Version 2.x.x:** Requires Java 17.\n- **Version 1.x.x:** Requires Java 14.\n\n## Usage\n\nConverts query into a MongoDB query object.\n\n```java\nMongoSpringSearch.mss(String query);\n\nMongoSpringSearch.mss(String query, Optional\u003cConfiguration\u003e configuration);\n```\n\n##### Arguments\n`query`: query string part of the requested API URL.\n\n`configuration`: object for advanced configuration (See below) [optional].\n\nYou can add custom methods to your repository:\n\n```java\n@Repository\npublic interface YourRepository extends MongoRepository\u003cYourDocument, String\u003e, YourCustomRepository {\n}\n```\n\nTo expand the `Spring MongoRepository` repository methods you can do it in the following way:\n\n```java\npublic interface YourCustomRepository {\n\tpublic List\u003cYourDocument\u003e findAll(String query);\n}\n```\n\nIn this class you can use `Mongo Spring Search`:\n\n```java\npublic class YourCustomRepositoryImpl implements YourCustomRepository {\n\n\tprivate MongoTemplate mongoTemplate;\n\t\n\t@Autowired\n\tpublic YourCustomRepositoryImpl(MongoTemplate mongoTemplate) {\n\t\tthis.mongoTemplate = mongoTemplate;\n\t}\n\t\n\t@Override\n\tpublic List\u003cYourDocument\u003e findAll(String query) {\n\t\treturn mongoTemplate.find(MongoSpringSearch.mss(query), YourDocument.class);\n\t}\n}\n```\n\nUse it in your controller:\n\n```java\n@GetMapping\npublic ResponseEntity\u003cList\u003cYourResponse\u003e\u003e yourFunctionNameHere(HttpServletRequest request) {\n\treturn ResponseEntity.ok().body(yourRepository.findAll(request.getQueryString()));\n}\n```\n\n##### Example\n\n```java\nQuery query = MongoSpringSearch.mss(\"status=sent\u0026date\u003e2020-01-06T14:00:00.000Z\u0026author.firstname=Jhon\u0026skip=50\u0026limit=100\u0026sort=-date\u0026fields=id,date\");\n```\n\n## Supported features\n\n### Filtering\n\n| Operator      \t| URI               \t| Example                        \t|\n| -----------------\t| ---------------------\t| ---------------------------------\t| \n| `$eq`          \t| `key=val`\t\t\t\t| `type=public`        \t\t\t\t|\n| `$ne`          \t| `key!=val`        \t| `status!=SENT`                    |\n| `$gt`          \t| `key\u003eval`             | `price\u003e5`                        |\n| `$gte`         \t| `key\u003e=val`            | `price\u003e=9`                       |\n| `$lt`          \t| `key\u003cval`             | `date\u003c2020-01-01T14:00:00.000Z`   |\n| `$lte`         \t| `key\u003c=val`            | `priority\u003c=-5`                    |\n| `$in`          \t| `key=val1,val2`       | `status=QUEUED,DEQUEUED`          |\n| `$nin`          \t| `key!=val1,val2`      | `status!=QUEUED,DEQUEUED`         |\n| `$exists`         | `key`          \t\t| `email`              \t\t\t\t|\n| `$exists`         | `!key`         \t\t| `!email`                    \t\t|\n| `$regex`      \t| `key=/value/\u003copts\u003e`\t| `email=/@gmail\\.com$/`\t\t\t|\n| `$regex`        \t| `key!=/value/\u003copts\u003e`  | `phone!=/^58/`                    |\n\n\n### Pagination\n\nUseful to limit the number of records returned.\n\n- Operator keys are `skip` and `limit`.\n- Use `limit` operator to limit the number of records returned.\n- Use `skip` operator to skip the specified number of records.\n\n```json\nskip=20\u0026limit=10\n```\n\n### Sorting\n\nUseful to sort returned records.\n\n- Operator key is `sort`. \n- It accepts a comma-separated list of fields.\n- Use `-` prefixes to sort in descending order.\n- Use `+` prefixes to sort in ascedending order.\n\n```json\nsort=id,-date\n```\n\n### Projection\n\nUseful to limit fields to return in each records.\n\n- Operator key is `fields`.\n- It accepts a comma-separated list of fields.\n\n```json\nfields=firstname,lastname,phone,email\n```\n\n**Note:** \n* The `_id` field (returned by default).\n\n\n### Advanced queries\n\nFor more advanced usage (`and`, `or` logic operations), pass query `filter` as string with the logical operations, for example:\n\n```json\nfilter=(country=Mexico OR country=Spain) and gender=female\n````\n\n##### What operations are possible?\n\n* Filtering operations.\n* The `AND/and` operator.\n* The `OR/or` operator.\n* Parenthesis can be used for grouping.\n\n## Available options\n\nYou can use advanced options:\n\n```java\nConfiguration(Map\u003cString, CastType\u003e casters, Integer defaultLimit, Integer maxLimit)\n```\n\n* `casters` object to specify custom casters, key is the caster name, and value is a type (`BOOLEAN, NUMBER, PATTERN, DATE, STRING`).\n* `defaultLimit` which contains custom value to return records.\n* `maxLimit` which contains custom value to return a maximum of records.\n\n### Customize limit value\n\nYou can specify your own maximum or default limit value.\n\n* `defaultLimit`: custom value to return records.\n* `maxLimit`: custom value to return a maximum of records.\n\n```java\nConfiguration options = new Configuration(null, 10, 500);\n\nMongoSpringSearch.mss(\"organizationId=123\u0026skip=10\u0026limit=1000\", Optional.of(options));\n```\n\n### Specify casting per param keys\n\nYou can specify how query parameter values are casted by passing an object.\n\n* `casters`: object which map keys to casters.\n\n```java\nMap\u003cString, CastType\u003e casters = new HashMap\u003cString, CastType\u003e();\ncasters.put(\"key1\", CastType.STRING);\ncasters.put(\"key2\", CastType.NUMBER);\ncasters.put(\"key3\", CastType.STRING);\ncasters.put(\"key4\", CastType.OBJECT_ID);\ncasters.put(\"key5\", CastType.BOOLEAN);\n\t\t\nConfiguration options = new Configuration(casters, null, null);\nMongoSpringSearch.mss(\"key1=VALUE\u0026key2=10\u0026key3=20\u0026key4=666fde1af688038e64d6b58a\u0026key5=true\", Optional.of(options));\n```\n\n## Contributing\n\nShould you like to provide any feedback, please open up an Issue, I appreciate feedback and comments. Any contributions you make are **greatly appreciated**.\n\n1. Fork the Project\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing-feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis software is released under the MIT license. See `LICENSE` for more information.\n\n\n[license-shield]: https://img.shields.io/badge/License-MIT-yellow.svg\n[license-url]: https://github.com/ajclopez/mongo-spring-search/blob/master/LICENSE.txt\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajclopez%2Fmongo-spring-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajclopez%2Fmongo-spring-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajclopez%2Fmongo-spring-search/lists"}