monger.collection — com.novemberain/monger 1.6.0

Provides key functionality for interaction with MongoDB: inserting, querying, updating and deleting documents, performing Aggregation Framework queries, creating and dropping indexes, creating collections and more.

For more advanced read queries, see monger.query.

Related documentation guides:

• http://clojuremongodb.info/articles/getting_started.html
• http://clojuremongodb.info/articles/inserting.html
• http://clojuremongodb.info/articles/querying.html
• http://clojuremongodb.info/articles/updating.html
• http://clojuremongodb.info/articles/deleting.html
• http://clojuremongodb.info/articles/aggregation.html

aggregate clj

(aggregate collection stages)

Performs aggregation query. MongoDB 2.1/2.2+ only.

See http://docs.mongodb.org/manual/applications/aggregation/ to learn more.

any? clj

(any? collection)

(any? collection conditions)

(any? db collection conditions)

Whether the collection has any items at all, or items matching query.

EXAMPLES:

;; whether the collection has any items (mgcol/any? collection)

(mgcol/any? collection {:language "Clojure"}))

count clj

(count collection)

(count collection conditions)

(count db collection conditions)

Returns the number of documents in this collection.

Takes optional conditions as an argument.

(monger.collection/count collection)

(monger.collection/count collection {:first_name "Paul"})

create clj

(create collection options)

(create db collection options)

Creates a collection with a given name and options.

Options are:

:capped (pass true to create a capped collection) :max (number of documents) :size (max allowed size of the collection, in bytes)

EXAMPLE:

;; create a capped collection (monger.collection/create "coll" {:capped true :size 100000 :max 10})

create-index clj

(create-index collection keys)

(create-index collection keys options)

(create-index db collection keys options)

Forces creation of index on a set of fields, if one does not already exists.

EXAMPLES

;; Will create an index on the "language" field
(monger.collection/create-index collection {"language" 1})
(monger.collection/create-index collection {"language" 1} {:unique true :name "unique_language"})

distinct clj

(distinct collection key)

(distinct collection key query)

(distinct db collection key query)

Finds distinct values for a key

drop clj

(drop collection)

(drop db collection)

Deletes collection from database.

EXAMPLE:

(monger.collection/drop "collection-to-drop")

drop-index clj

(drop-index collection idx-name)

(drop-index db collection idx-name)

Drops an index from this collection.

drop-indexes clj

(drop-indexes collection)

(drop-indexes db collection)

Drops all indixes from this collection.

empty? clj

(empty? collection)

(empty? db collection)

Whether the collection is empty.

EXAMPLES: (mgcol/empty? "things")

ensure-index clj

(ensure-index collection keys)

(ensure-index collection keys options)

(ensure-index collection keys name unique?)

Creates an index on a set of fields, if one does not already exist. This operation is inexpensive in the case when an index already exists.

Options are:

:unique (boolean) to create a unique index :name (string) to specify a custom index name and not rely on the generated one

EXAMPLES

;; create a regular index ;; clojure.core/array-map produces an ordered map (monger.collection/ensure-index "documents" (array-map "language" 1)) ;; create a unique index (monger.collection/ensure-index "pages" (array-map :url 1) {:unique true})

exists? clj

(exists? collection)

(exists? db collection)

Checks weather collection with certain name exists.

EXAMPLE:

(monger.collection/exists? "coll")

find clj

(find collection)

(find collection ref)

(find collection ref fields)

(find db collection ref fields)

Queries for objects in this collection. This function returns DBCursor, which allows you to iterate over DBObjects. If you want to manipulate clojure sequences maps, please @find-maps@.

EXAMPLES: ;; return all objects in this collection. (mgcol/find "people")

;; return all objects matching query (mgcol/find "people" {:company "Comp Corp"})

;; return all objects matching query, taking only specified fields (mgcol/find "people" {:company "Comp Corp"} [:first_name :last_name])

find-and-modify clj

(find-and-modify collection
                 conditions
                 document
                 &
                 {:keys [fields sort remove return-new upsert keywordize]
                  :or {fields nil
                       sort nil
                       remove false
                       return-new false
                       upsert false
                       keywordize true}})

Atomically modify a document (at most one) and return it.

EXAMPLES:

;; Find and modify a document (mgcol/find-and-modify collection {:language "Python"} {:language "Clojure"})

;; If multiple documents match, choose the first one in the specified order (mgcol/find-and-modify collection {:language "Python"} {:language "Clojure"} :sort {:language -1})

;; Remove the object before returning (mgcol/find-and-modify collection {:language "Python"} {} :remove true)

;; Return the modified object instead of the old one (mgcol/find-and-modify collection {:language "Python"} {:language "Clojure"} :return-new true)

;; Retrieve a subset of fields (mgcol/find-and-modify collection {:language "Python"} {:language "Clojure"} :fields [ :language ])

;; Create the object if it doesn't exist (mgcol/find-and-modify collection {:language "Factor"} {:language "Clojure"} :upsert true)

find-by-id clj

(find-by-id collection id)

(find-by-id collection id fields)

(find-by-id db collection id fields)

Returns a single object with matching _id field.

EXAMPLES:

(mgcol/find-one-by-id collection (ObjectId. "4ef45ab4744e9fd632640e2d"))

;; Return only :language field. ;; Note that _id field is always returned. (mgcol/find-one-by-id collection (ObjectId. "4ef45ab4744e9fd632640e2d") [:language])

find-map-by-id clj

(find-map-by-id collection id)

(find-map-by-id collection id fields)

(find-map-by-id collection id fields keywordize)

Returns a single object, converted to map with matching _id field.

find-maps clj

(find-maps collection)

(find-maps collection ref)

(find-maps collection ref fields)

(find-maps db collection ref fields)

Queries for objects in this collection. This function returns clojure Seq of Maps. If you want to work directly with DBObject, use find.

find-one clj

(find-one collection ref)

(find-one collection ref fields)

(find-one db collection ref fields)

Returns a single DBObject from this collection matching the query.

EXAMPLES:

(mgcol/find-one collection {:language "Clojure"})

;; Return only :language field. ;; Note that _id field is always returned. (mgcol/find-one collection {:language "Clojure"} [:language])

find-one-as-map clj

(find-one-as-map collection ref)

(find-one-as-map collection ref fields)

(find-one-as-map collection ref fields keywordize)

Returns a single object converted to Map from this collection matching the query.

find-seq clj

(find-seq collection)

(find-seq collection ref)

(find-seq collection ref fields)

(find-seq db collection ref fields)

Queries for objects in this collection, returns ISeq of DBObjects.

indexes-on clj

(indexes-on collection)

Return a list of the indexes for this collection.

EXAMPLES

(monger.collection/indexes-on collection)

insert clj

(insert collection document)

(insert collection document concern)

(insert db collection document concern)

Saves @document@ to @collection@ and returns write result monger.result/ok? and similar functions operate on. You can optionally specify WriteConcern.

In case you need the exact inserted document returned, with the :_id key generated, use monger.collection/insert-and-return instead.

EXAMPLES:

;; returns write result
(monger.collection/insert "people" {:name "Joe", :age 30})

(monger.collection/insert "people" {:name "Joe", :age 30, WriteConcern/SAFE})

insert-and-return clj

(insert-and-return collection document)

(insert-and-return collection document concern)

(insert-and-return db collection document concern)

Like monger.collection/insert but returns the inserted document as a persistent Clojure map.

If the :_id key wasn't set on the document, it will be generated and merged into the returned map.

EXAMPLES:

 ;; returns the entire document with :_id generated
 (monger.collection/insert-and-return "people" {:name "Joe", :age 30})

 (monger.collection/insert-and-return "people" {:name "Joe", :age 30, WriteConcern/SAFE})

insert-batch clj

(insert-batch collection documents)

(insert-batch collection documents concern)

(insert-batch db collection documents concern)

Saves @documents@ do @collection@. You can optionally specify WriteConcern as a third argument.

EXAMPLES:

(monger.collection/insert-batch "people" [{:name "Joe", :age 30}, {:name "Paul", :age 27}])

(monger.collection/insert-batch "people" [{:name "Joe", :age 30}, {:name "Paul", :age 27}] WriteConcern/NORMAL)

map-reduce clj

(map-reduce collection js-mapper js-reducer output query)

(map-reduce collection js-mapper js-reducer output output-type query)

Performs a map reduce operation

remove clj

(remove collection)

(remove collection conditions)

(remove db collection conditions)

Removes objects from the database.

EXAMPLES

(monger.collection/remove collection) ;; Removes all documents from DB

(monger.collection/remove collection {:language "Clojure"}) ;; Removes documents based on given query

remove-by-id clj

(remove-by-id collection id)

(remove-by-id db collection id)

Removes a single document with given id

rename clj

(rename from to)

(rename from to drop-target)

(rename db from to drop-target)

Renames collection.

EXAMPLE:

(monger.collection/rename "old_name" "new_name")

save clj

(save collection document)

(save collection document write-concern)

(save db collection document write-concern)

Saves an object to the given collection (does insert or update based on the object _id).

If the object is not present in the database, insert operation will be performed. If the object is already in the database, it will be updated.

This function returns write result. If you want to get the exact persisted document back, use save-and-return.

EXAMPLES

(monger.collection/save "people" {:first_name "Ian" :last_name "Gillan"})

save-and-return clj

(save-and-return collection document)

(save-and-return collection document write-concern)

(save-and-return db collection document write-concern)

Saves an object to the given collection (does insert or update based on the object _id).

If the object is not present in the database, insert operation will be performed. If the object is already in the database, it will be updated.

This function returns the exact persisted document back, including the :_id key in case of an insert.

If you want to get write result back, use save.

EXAMPLES

(monger.collection/save-and-return "people" {:first_name "Ian" :last_name "Gillan"})

system-collection-pattern clj

system-collection? clj

(system-collection? collection)

Evaluates to true if the given collection name refers to a system collection. System collections are prefixed with system. or fs. (default GridFS collection prefix)

update clj

(update collection
        conditions
        document
        &
        {:keys [upsert multi write-concern]
         :or {upsert false
              multi false
              write-concern monger.core/*mongodb-write-concern*}})

Performs an update operation.

Please note that update is potentially destructive operation. It will update your document with the given set emptying the fields not mentioned in (^Map document). In order to only change certain fields, please use "$set".

EXAMPLES

(monger.collection/update "people" {:first_name "Raul"} {"$set" {:first_name "Paul"}})

You can use all the Mongodb Modifier Operations ($inc, $set, $unset, $push, $pushAll, $addToSet, $pop, $pull $pullAll, $rename, $bit) here, as well

EXAMPLES

(monger.collection/update "people" {:first_name "Paul"} {"$set" {:index 1}}) (monger.collection/update "people" {:first_name "Paul"} {"$inc" {:index 5}})

(monger.collection/update "people" {:first_name "Paul"} {"$unset" {:years_on_stage 1}})

It also takes modifiers, such as :upsert and :multi.

EXAMPLES

;; add :band field to all the records found in "people" collection, otherwise only the first matched record ;; will be updated (monger.collection/update "people" {} {"$set" {:band "The Beatles"}} :multi true)

;; inserts the record if it did not exist in the collection (monger.collection/update "people" {:first_name "Yoko"} {:first_name "Yoko" :last_name "Ono"} :upsert true)

By default :upsert and :multi are false.

update-by-id clj

(update-by-id collection
              id
              document
              &
              {:keys [upsert write-concern]
               :or {upsert false
                    write-concern monger.core/*mongodb-write-concern*}})

Update a document with given id

upsert clj

(upsert collection
        conditions
        document
        &
        {:keys [multi write-concern]
         :or {multi false write-concern monger.core/*mongodb-write-concern*}})

Performs an upsert.

This is a convenience function that delegates to monger.collection/update and sets :upsert to true.

See monger.collection/update documentation