monger.collection documentation

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

(aggregate collection stages)
Performs aggregation query. MongoDB 2.1/2.2+ only.

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

any?

(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

(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

(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

(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

(distinct collection key)(distinct collection key query)(distinct db collection key query)
Finds distinct values for a key

drop

(drop collection)(drop db collection)
Deletes collection from database.

EXAMPLE:

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

drop-index

(drop-index collection idx-name)(drop-index db collection idx-name)
Drops an index from this collection.

drop-indexes

(drop-indexes collection)(drop-indexes db collection)
Drops all indixes from this collection.

empty?

(empty? collection)(empty? db collection)
Whether the collection is empty.

EXAMPLES:
   (mgcol/empty? "things")

ensure-index

(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?

(exists? collection)(exists? db collection)
Checks weather collection with certain name exists.

EXAMPLE:

   (monger.collection/exists? "coll")

find

(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

(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

(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

(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

(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

(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

(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

(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

(indexes-on collection)
Return a list of the indexes for this collection.

EXAMPLES

  (monger.collection/indexes-on collection)

insert

(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

(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

(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

(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

(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

(remove-by-id collection id)(remove-by-id db collection id)
Removes a single document with given id

rename

(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

(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

(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?

(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

(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

(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

(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