Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
  • 3 commits
  • 3 files changed
  • 0 commit comments
  • 1 contributor
Showing with 121 additions and 35 deletions.
  1. +0 −1  Capfile
  2. +120 −33 articles/getting_started.md
  3. +1 −1  index.html
View
1  Capfile
@@ -1 +0,0 @@
-
View
153 articles/getting_started.md
@@ -9,15 +9,15 @@ This guide combines an overview of Monger with a quick tutorial that helps you t
It should take about 10 minutes to read and study the provided code examples. This guide covers:
* Feature of Monger, why Monger was created
+ * Clojure and MongoDB version requirements
* How to add Monger dependency to your project
* Basic operations (created, read, update, delete)
* Overview of Monger Query DSL
* Overview of how Monger integrates with libraries like clojure.data.json and JodaTime.
- * GridFS support
- * Clojure and MongoDB version requirements
This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a> (including images & stylesheets). The source is available [on Github](https://github.com/clojurewerkz/monger.docs).
+
## What version of Monger does this guide cover?
This guide covers Monger 1.0.0-beta2, the most recent pre-release version. Monger is a young project but most of the public API
@@ -29,22 +29,6 @@ is fleshed out and will not change before the 1.0 release.
Monger is an idiomatic Clojure wrapper around MongoDB Java driver. It offers powerful expressive query DSL, strives to support
every MongoDB 2.0+ feature, has next to no performance overhead and is well maintained.
-### Project Goals
-
-There is one MongoDB client for Clojure that has been around since 2009. So, why create another one? Monger authors
-wanted a client that will
-
- * Support most of MongoDB 2.0+ features but only those that really matter. Grouping the way it is done today, for example, does not (it is easier to just use Map/Reduce directly).
- * Be well documented.
- * Be well tested.
- * Be maintained, do not carry technical debt from 2009 forever.
- * Target Clojure 1.3.0 and later from the ground up.
- * Integrate with libraries like [clojure.data.json](https://github.com/clojure/data.json), [clojure.core.cache](https://github.com/clojure/core.cache) and [clj-time](https://github.com/seancorfield/clj-time).
- * Provide support for unit testing: factories/fixtures DSL, collection cleaner functions and so on.
- * Support URI connections to be friendly to Heroku and other PaaS providers.
- * Learn from other clients like the Java and Ruby ones.
- * Integrate usage of JavaScript files and ClojureScript (as soon as the compiler gets artifact it is possible to depend on for easy embedding).
-
### What Monger is not
@@ -54,6 +38,17 @@ vectors, strings, dates and so on. This approach has pros and cons but (we belie
reducing incidental complexity. It also fits MongoDB data model very well.
+## Supported Clojure versions
+
+Monger is built from the ground up for Clojure 1.3 and later. n
+
+
+## Supported MongoDB versions
+
+Monger currently uses MongoDB Java driver 2.7.x under the hood and thus supports MongoDB 2.0 and later versions. Please note that some
+features may be specific to MongoDB 2.2 and later versions.
+
+
## Adding Monger Dependency To Your Project
### With Leiningen
@@ -122,30 +117,56 @@ Finder functions in Monger return either Clojure maps (commonly used) or Java dr
For example, `monger.collection/find` returns a `DBCursor`:
-{% gist 0 %}
+{% gist d9c31fe7108941b3b94a %}
`monger.collection/find-map-by-id` finds one document by `ObjectId` and automatically converts it to a Clojure map
before returning:
-{% gist 0 %}
+{% gist 976c79a1ba8eaac491b2 %}
### Using query DSL
For cases when it is necessary to combine sorting, limiting or offseting results, pagination and even more advanced features
like cursor snapshotting or manual index hinting, Monger provides a very powerful query DSL. Here is what it looks like:
-{% gist 0 %}
+{% gist b52c7ae2312c8c6b64ee %}
+
+
+
## How to Update Documents with Monger
+Monger's update API follows the following simple rule: the "syntax" for condition and update document structure is
+the same or as close as possible to MongoDB shell and official drivers. In addition, Monger provides several
+convenience functions for common cases, for example, finding documents by id.
+
+
+### Regular Updates
+
`monger.collection/update` is the most commonly used way of updating documents. `monger.collection/update-by-id` is useful
when document id is known:
{% gist 8313a67bac %}
+### Upserts
+
+MongoDB supports upserts, "update or insert" operations. To do an upsert with Monger, use `monger.collection/update` function with `:upsert` option set to true:
+
+{% gist 745200324f719b68bb27 %}
+
+Note that upsert only inserts one document. Learn more about upserts in [this MongoDB documentation section](www.mongodb.org/display/DOCS/Updating#Updating-update()).
+
+
+### Atomic Modifiers
+
+Modifier operations are highly-efficient and useful when updating existing values; for instance, they're great for incrementing counters, setting individual fields, updating fields that are arrays and so on.
+
+MongoDB supports modifiers via update operation and Monger API works the same way: you pass a document with modifiers
+to `monger.collection/update`. For example, to increment number of views for a particular page:
+
+{% gist 06ac96f1306e274ec82b %}
-TBD: upsert examples
## How to Remove Documents with Monger
@@ -156,11 +177,6 @@ when document id is known.
{% gist 44e3cdae129deeea7512 %}
-## Monger Query DSL
-
-TBD
-
-
## Integration With Other Libraries
Monger heavily relies on relatively recent Clojure features like protocols to integrate with libraries like
@@ -168,16 +184,87 @@ Monger heavily relies on relatively recent Clojure features like protocols to in
application instead of figuring out how to glue two libraries together.
-TBD
+### clojure.data.json
+
+Many applications that use MongoDB and Monger have to serialize documents stored in the database to JSON and pass
+them to other applications using HTTP or messaging protocols such as [AMQP 0.9.1](http://bit.ly/amqp-model-explained) or [ZeroMQ](http://zeromq.org).
+
+This means that MongoDB data types (object ids, documents) need to be serialized. While BSON, data format used by
+MongoDB, is semantically very similar to JSON, MongoDB drivers do not typically provide serialization to JSON
+and JSON serialization libraries typically do not support MongoDB data types.
+
+Monger provides a convenient feature for `clojure.data.json`, a pretty popular modern JSON serialization library
+for Clojure. The way it works is Monger will extend [clojure.data.json](https://github.com/clojure/data.json) serialization protocol to MongoDB Java
+driver data types: `org.bson.types.ObjectId` and `com.mongodb.DBObject` if you opt-in for it.
+To use it, you need to add `clojure.data.json` dependency to your project, for example (with Leiningen)
+
+{% gist 2f465e2e9c71ac9aaaef %}
+
+
+and then require `monger.json` namespace like so:
+
+{% gist 5f03c5acaa0b39cf7a09 %}
+
+when loaded, code in that namespace will extend necessary protocols and that's it. Then you can pass documents
+that contain object ids in them to JSON serialization functions of `clojure.data.json` and everything will
+just work.
+
+This feature is optional: Monger does not depend on `clojure.data.json` and won't add unused dependencies
+to your project.
+
+
+
+### clj-time, Joda Time
+
+Because of various shortcomings of Java date/time classes provided by the JDK, many projects choose to use [Joda Time](http://joda-time.sourceforge.net/) to work with dates.
+
+To be able to insert documents with Joda Time date values in them, you need to require `monger.joda-time` namespace:
+{% gist e4447d7a88eacd754d9a %}
-## GridFS Support
+Just like with `clojure.data.json` integration, there is nothing else you have to do. This feature is optional:
+Monger does not depend on `clj-time` or `Joda Time` and won't add unused dependencies to your project.
+
+
+
+### clojure.core.cache
+
+Monger provides a MongoDB-backed cache implementation that conforms to the `clojure.core.cache` protocol.
+It uses capped collections for caches. You can use any many cache data structure instances as your application
+may need.
TBD
-## Clojure and MongoDB Version Requirements
-Monger is built from the ground up for Clojure 1.3 and later. It currently uses MongoDB Java driver 2.7.x under
-the hood and thus supports MongoDB 2.0 and later versions. Please note that some features may be specific to MongoDB 2.2 and
-later versions.
+## Wrapping Up
+
+Congratulations, you now know how to do most common operations with Monger. Monger and MongoDB both have much
+more to them to explore. Other guides explain these and other features in depth, as well as rationale and
+use cases for them.
+
+To stay up to date with Monger development, [follow @ClojureWerkz on Twitter](http://twitter.com/ClojureWerkz) and
+join our [mailing list about Monger, Clojure and MongoDB](https://groups.google.com/forum/#!forum/clojure-monger).
+
+
+## What to Read Next
+
+Documentation is organized as a number of guides, covering all kinds of topics.
+
+We recommend that you read the following guides first, if possible, in this order:
+
+ * [Connecting to MongoDB](/guides/connecting.html)
+ * [Inserting documents](/guides/inserting.html)
+ * [Querying & finders](/guides/querying.html)
+ * [Updating documents](/guides/updating.html)
+ * [Deleting documents](/guides/deleting.html)
+ * [Integration with 3rd party libraries](/guides/integration.html)
+ * [Map/Reduce](/guides/mapreduce.html)
+ * [GridFS support](/guides/gridfs.html)
+
+
+## Tell Us What You Think!
+
+Please take a moment to tell us what you think about this guide on Twitter or the [Monger mailing list](https://groups.google.com/forum/#!forum/clojure-monger)
+
+Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.
View
2  index.html
@@ -35,7 +35,7 @@
</div>
<div class='span4'>
<h2>Batteries Included</h2>
- <p>Includes (optional) integration with popular Clojure libraries, unit testing support, core.cache implementation on top of MongoDB and more.</p>
+ <p>Includes (optional) integration with popular Clojure libraries, <a href="https://github.com/michaelklishin/validateur">Clojure validation library</a> conveniently provided, unit testing support, core.cache implementation on top of MongoDB and more.</p>
<p>
<a class='btn' href='#'>View details »</a>
</p>

No commit comments for this range

Something went wrong with that request. Please try again.