From 41c37746ac8acc8fd9b76e2ad6f3d112421db552 Mon Sep 17 00:00:00 2001 From: "Michael S. Klishin" Date: Tue, 31 Jan 2012 02:32:50 +0400 Subject: [PATCH] README updates --- README.md | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 184 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 75d794a..5c22bde 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,141 @@ wanted a client that will * Target Clojure 1.3.0 and later from the ground up. -## Usage +## Documentation & Examples We are working on documentation guides & examples site for the 1.0 release. In the meantime, please refer to the [test suite](https://github.com/michaelklishin/monger/tree/master/test/monger/test) for code examples. +## Connecting to MongoDB + +Monger supports working with multiple connections and/or databases but is optimized for applications that only use one connection +and one database. + +``` clojure +(ns my.service.server + (:require [monger core util])) + +;; localhost, default port +(monger.core/connect!) + +;; given host, given port +(monger.core/connect! { :host "db.megacorp.internal" :port 7878 }) +``` + +To set default database Monger will use, use `monger.core/get-db` and `monger.core/set-db!` functions in combination: + +``` clojure +(ns my.service.server + (:require [monger core]])) + +;; localhost, default port +(monger.core/connect!) +(monger.core/set-db! (monger.core/get-db "monger-test")) +``` + +To set default write concern, use `monger.core/set-default-write-concern!` function: + +``` clojure +(monger.core/set-default-write-concern! WriteConcern/FSYNC_SAFE) +``` + +By default Monger will use `WriteConcern/SAFE` as write concern. We believe that MongoDB Java driver (as well as other +official drivers) are using very unsafe defaults when no exceptions are raised, even for network issues. This does not sound +like a good default for most applications: many applications use MongoDB because of the flexibility, not extreme write throughput +requirements. + +## Inserting Documents + +To insert documents, use `monger.collection/insert` and `monger.collection/insert-batch` functions. + +``` clojure +(ns my.service.server + (:use [monger.core :only [connect! connect set-db! get-db]] + [monger.collection :only [insert insert-batch]]) + (:import [org.bson.types ObjectId] + [com.mongodb DB WriteResult])) + +;; localhost, default port +(connect!) +(set-db! (monger.core/get-db "monger-test")) + +;; without document id +(insert "document" { :first_name "John" :last_name "Lennon" }) + +;; multiple documents at once +(insert-batch "document" [{ :first_name "John" :last_name "Lennon" } + { :first_name "Paul" :last_name "McCartney" }]) + +;; with explicit document id +(insert "documents" { :_id (ObjectId.) :first_name "John" :last_name "Lennon" }) + +;; with a different write concern +(insert "documents" { :_id (ObjectId.) :first_name "John" :last_name "Lennon" } WriteConcern/JOURNAL_SAFE) + +;; with a different database +(let [archive-db (get-db "monger-test.archive")] + (insert archive-db "documents" { :first_name "John" :last_name "Lennon" } WriteConcern/NORMAL)) +``` + +### Write Performance + +Monger insert operations are efficient and have very little overhead compared to the underlying Java driver. Here +are some numbers on a MacBook Pro from fall 2010 with Core i7 and an Intel SSD drive: + +``` +Testing monger.test.stress +Inserting 1000 documents... +"Elapsed time: 38.317 msecs" +Inserting 10,000 documents... +"Elapsed time: 263.827 msecs" +Inserting 100,000 documents... +"Elapsed time: 1679.828 msecs" +``` + +With the `SAFE` write concern, it takes roughly 1.7 second to insert 100,000 documents. + + +## Regular Finders + +`monger.collection` namespace provides several finder functions that try to follow MongoDB query language as closely as possible, +even when providing shortcuts for common cases. + +`` clojure +(ns my.service.finders + (:require [monger.collection :as mc]) + (:use [monger.operators])) + +;; find one document by id, as Clojure map +(mc/find-map-by-id "documents" (ObjectId. "4ec2d1a6b55634a935ea4ac8")) + +;; find one document by id, as `com.mongodb.DBObject` instance +(mc/find-by-id "documents" (ObjectId. "4ec2d1a6b55634a935ea4ac8")) + +;; find one document as Clojure map +(mc/find-one-as-map "documents" { :_id (ObjectId. "4ec2d1a6b55634a935ea4ac8") }) + +;; find one document by id, as `com.mongodb.DBObject` instance +(mc/find-one "documents" { :_id (ObjectId. "4ec2d1a6b55634a935ea4ac8") }) + + +;; all documents as Clojure maps +(mc/find-maps "documents") + +;; all documents as `com.mongodb.DBObject` instances +(mc/find "documents") + +;; with a query, as Clojure maps +(mc/find-maps "documents" { :year 1998 }) + +;; with a query, as `com.mongodb.DBObject` instances +(mc/find "documents" { :year 1998 }) + +;; with a query that uses operators +(mc/find "products" { :price_in_subunits { $gt 4000 $lte 1200 } }) + +;; with a query that uses operators as strings +(mc/find "products" { :price_in_subunits { "$gt" 4000 "$lte" 1200 } }) +`` + ## Powerful Query DSL @@ -70,6 +201,33 @@ Query DSL supports composition, too: More code examples can be found [in our test suite](https://github.com/michaelklishin/monger/tree/master/test/monger/test). +## Updating Documents + +Use `monger.collection/update` and `monger.collection/save`. + + +## Removing Documents + +Use `monger.collection/remove`. + + +## Counting Documents + +Use `monger.collection/count`, `monger.collection/empty?` and `monger.collection/any?`. + + +## Determening Whether Operation Succeeded (or Failed) + +To be documented. + + +## Validators with Validateur + +Monger relies on [Validateur](http://github.com/michaelklishin/validateur) for data validation. + +To be documented. + + ## Integration With Popular Libraries Because Monger was built for Clojure 1.3 and later, it can take advantage of relatively new powerful Clojure features such as protocols. @@ -107,6 +265,31 @@ Now `clojure.data.json/write-json` and related functions will serialize JodaTime Clojure maps will instantiate JodaTime date time objects from `java.util.Date` instances MongoDB Java driver uses. +## Map/Reduce. Using JavaScript Resources. + +To be documented. + + +## Operations On Indexes + +To be documented. + + +## Database Commands + +To be documented. + + +## GridFS Support + +To be documented. + + +## Helper Functions + +To be documented. + + ## This is a Work In Progress