{"id":19416725,"url":"https://github.com/limansky/mongoquery","last_synced_at":"2025-04-24T13:33:03.108Z","repository":{"id":22844228,"uuid":"26191523","full_name":"limansky/mongoquery","owner":"limansky","description":"Scala MongoDB query builder","archived":false,"fork":false,"pushed_at":"2019-07-01T21:13:29.000Z","size":223,"stargazers_count":26,"open_issues_count":3,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-08-24T01:34:43.480Z","etag":null,"topics":["casbah","mongodb","reactivemongo","scala"],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/limansky.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}},"created_at":"2014-11-04T22:23:40.000Z","updated_at":"2023-09-26T14:21:30.000Z","dependencies_parsed_at":"2022-08-05T20:01:02.811Z","dependency_job_id":null,"html_url":"https://github.com/limansky/mongoquery","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/limansky%2Fmongoquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/limansky%2Fmongoquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/limansky%2Fmongoquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/limansky%2Fmongoquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/limansky","download_url":"https://codeload.github.com/limansky/mongoquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223954837,"owners_count":17231189,"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":["casbah","mongodb","reactivemongo","scala"],"created_at":"2024-11-10T13:04:22.773Z","updated_at":"2024-11-10T13:04:23.449Z","avatar_url":"https://github.com/limansky.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"MongoQuery\n==========\n\n[![Build Status](https://travis-ci.org/limansky/mongoquery.svg?branch=master)](https://travis-ci.org/limansky/mongoquery)\n[![codecov](https://codecov.io/gh/limansky/mongoquery/branch/master/graph/badge.svg)](https://codecov.io/gh/limansky/mongoquery)\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.limansky/mongoquery-core_2.11.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.limansky/mongoquery-core_2.11)\n\nMongoQuery is a macro based MongoDB query builder for Scala.\n\nCurrently the [MongoDB][] queries API requires to construct DBObjects explicitly.\nThis makes even simple queries bulky.  Even though you are using Casbah DSL\nit often still requires to create `MongoDBObject`s, and also requires to\nstudy new syntax, instead of using MongoDB queries.  The purpose of this\nproject is to provide a simple API for creating queries from strings.  The\ngoal is to make compile time queries syntax checking (as much as possible).\n\nHow to use\n----------\n\n### Installation ###\n\nSince version 0.7 MongoQuery supports only Scala 2.11 and 2.12.  If you are still using Scala 2.10\nyou can use MongoQuery 0.6 (or any version before).\n\nMongoQuery is published to Sonatype maven repository.  Add following dependency to\nlibraryDependencies in your SBT build file:\n\n```\n\"com.github.limansky\" %% \"mongoquery-casbah\" % \"0.7\"       // for Casbah users\n\"com.github.limansky\" %% \"mongoquery-reactive\" % \"0.7\"     // for ReactiveMongo users\n\"com.github.limansky\" %% \"mongoquery-scala-driver\" % \"0.7\" // for Mongo Scala driver\n```\n\nIf you want use latest development version:\n\n```\n\"com.github.limansky\" %% \"mongoquery-casbah\" % \"0.8-SNAPSHOT\"       // Casbah users\n\"com.github.limansky\" %% \"mongoquery-reactive\" % \"0.8-SNAPSHOT\"     // ReactiveMongo users\n\"com.github.limansky\" %% \"mongoquery-scala-driver\" % \"0.8-SNAPSHOT\" // for Mongo Scala driver\n```\n\n### mq interpolator ###\n\nThe `mq` string interpolator converts string to the BSON objects. If you use\n[Casbah][] it creates `DBObjects`:\n\n```Scala\nimport com.github.limansky.mongoquery.casbah._\n\ndef findByName(name: String) = {\n  myCollection.find(mq\"{ name : $name}\")\n}\n\n```\n\nFor [ReactiveMongo][] it creates `BSONDocument`s:\n\n```Scala\nimport com.github.limansky.mongoquery.reactive._\n\ncollection.\n  find(mq\"\"\"{ firstName : \"Jack\" }\"\"\", mq\"{ lastName : 1, _id : 1 }\").\n  cursor[BSONDocument].\n  enumerate().apply(Iteratee.foreach { doc =\u003e\n  println(\"found document: \" + BSONDocument.pretty(doc))\n})\n```\n\nFor [Mongo Scala Driver][] it creates `BsonDocument`s:\n\n```Scala\nimport com.github.limansky.mongoquery.scaladriver._\n\ncollection.insertOne(mq\"\"\"{ name: \"John\", lastName: \"Doe\", age : 42 }\"\"\")\n```\n\nSince the query is defined inside of the string interpolator, the words started\nwith `$` are handled as variable references.  To type MongoDB operator use `$$`, e.g:\n\n```Scala\ndef makeOlder(age: Int) = {\n  people.update(mq\"\"\"{ age : { $$lt : $age } }\"\"\",\n                mq\"\"\"{ $$inc : { age : 1 }}\"\"\",\n                multi = 1)\n}\n```\n\nSince the interpolator is implemented using macro it can perform compile time checks\nof provided queries. The code will not compile if the query is malformed.  Also\nMongoQuery checks if all MongoDB operators are known.\n\n```Scala\n[error] Test.scala:44: Unknown operator '$kte'. Possible you mean '$lte'\n[error]     val query = mq\"{start : {$$kte : $start}}\"\n[error]                              ^\n\n[error] Test.scala:49: '{' expected, but Variable found\n[error]     val q = mq\"{ color : {$$in : $colors}\"\n[error]                                ^\n```\n\nUnfortunately, some errors messages does not reflect the error itself.  I'm working\non it, but it seems like the issue in the Scala Parser Combinators library.\n\n### Built-in types ###\n\nMongoQuery supports several MongoDB specific literal types.\n\n - ObjectIds. `mq\"\"\"{ clientId : ObjectId(\"01234567890abcdef1234\") }\"\"\"`\n - Booleans. `mq\"{ expired : false }\"`\n - Regular expressions (since 0.5). `mq\"{ name : /^joe/i }\"`\n\n### mqt interpolator ###\n\n`mqt` is another one interpolator adding type checking feature.  If you have a model\nclasses, you can check if the query contains only fields available in the class. E.g.:\n\n```Scala\ncase class Phone(kind: String, number: String)\ncase class Person(name: String, age: Int, phones: List[Phone])\n\n// OK\npersons.update(mq\"{}\", mqt\"{$$inc : { age : 1 }}\"[Person])\n\n// Failed, person doesn't contain field 'nme'\npersons.update(mq\"{}\", mqt\"\"\"{$$set : { nme : \"Joe\" }}\"\"\"[Person])\n\n//Failed, name is not indexed field\npersons.find(mqt\"{ name.1 : 'Joe' }\"[Person])\n\n// OK\npersons.find(mqt\"{ phone.number : '223322' }\"[Person])\n\n// Failed, Phone doesn't contain field num\npersons.find(mqt\"{ phone.num : '223322' }\"[Person])\n```\n\n### Runtime parsing ###\n\nMongoQuery also provides runtime parsers for both backends. It might be useful for\ntesting purposes, or if you generate queries on runtime, or for converting JSON to\nBSON.  For example:\n\n```Scala\nimport com.github.limansky.mongoquery.casbah.BSONParser\n\npersons.find(BSONParser.parse(\"\"\"{ age : { $lt : 42 }}\"\"\"))\n```\n\nFeedback\n--------\n\nAny feedback is very welcome!  You can ask any questions in [MongoQuery mailing list][maillist].\n\n[MongoDB]: http://www.mongodb.org/\n[Casbah]: https://github.com/mongodb/casbah\n[ReactiveMongo]: http://reactivemongo.org/\n[Mongo Scala Driver]: http://mongodb.github.io/mongo-scala-driver/\n[maillist]: https://groups.google.com/forum/#!forum/mongoquery-users\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flimansky%2Fmongoquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flimansky%2Fmongoquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flimansky%2Fmongoquery/lists"}