somnium.congomongo — congomongo 2.5.0

Various wrappers and utilities for the mongodb-java-driver

->tagset clj

(->tagset tag)

add-index! clj

(add-index!
  collection
  fields
  {:name nil :unique false :sparse false :partial-filter-expression nil})

Adds an index on the collection for the specified fields if it does not exist. Ordering of fields is significant; an index on [:a :b] is not the same as an index on [:b :a].

By default, all fields are indexed in ascending order. To index a field in descending order, specify it as a vector with a direction signifier (i.e. -1), like so:

[:a [:b -1] :c]

This will generate an index on:

:a ascending, :b descending, :c ascending

Similarly, [[:a 1] [:b -1] :c] will generate the same index (1 indicates ascending order, the default).

Optional parameters include: :name -> defaults to the system-generated default :unique -> defaults to false :sparse -> defaults to false :background -> defaults to false :partial-filter-expression -> defaults to no filter expression

aggregate clj

(aggregate collection
           op
           &
           ops
           {:as :clojure
            :from :clojure
            :read-preference nil
            :batch-size nil
            :allow-disk-use? nil
            :max-time-ms nil
            :bypass-document-validation? nil
            :collation nil})

Executes a pipeline of operations using the Aggregation Framework.

Required parameters: collection -> the database collection name (string, keyword, or symbol) op -> the 1st (and, possibly, only) operation to be performed in the aggregation pipeline

Optional parameters include: :ops -> other operations (2nd, 3rd, etc.) to be performed in the aggregation pipeline :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (op and optional ops) format (same default/options as for :as) :read-preference -> set the read preference (e.g. :primary or ReadPreference instance) :batch-size -> set the size of batches to use when iterating over results (by default, server-chosen) :allow-disk-use? -> set whether to enable external sort capabilities (i.e. whether or not aggregation stages can write data to temporary files); if set to false, a $sort stage produces an error if the operation consumes 10 percent or more RAM :max-time-ms -> set the max server execution time for the aggregation command (default is 0, no limit) :bypass-document-validation? -> set the bypass document level validation flag :collation -> set the collation

Returns a map with the following keys: :serverUsed -> a string representing the server address :result -> the result of the aggregation (if successful) :ok -> 1.0 for success

close-connection clj

(close-connection conn)

Closes the conn and unsets it as the active connection if necessary.

collection-exists? clj

(collection-exists? collection)

Query whether the named collection has been created within the DB.

collections clj

(collections)

Returns the set of collections stored in the current database

command clj

command! clj

(command! cmd {:as :clojure :from :clojure :read-preference nil :encoder nil})

Executes a database command.

The MongoDB command interface provides access to all non CRUD database operations: authentication; user, role and session management; replication and sharding; database administration, diagnostics and auditing — are all accomplished with commands. All "User Commands" are supported as well. See Database Commands for the full list.

Required parameters: cmd -> a string representation of the command to be executed

Optional parameters include: :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (cmd) format (same default and options as for :as) :read-preference -> set the read preference (e.g. :primary or ReadPreference instance); determines where to execute the given command; this will only be applied for a subset of commands (see the DB#getCommandReadPreference) :encoder -> set the encoder that knows how to serialise the command

connection? clj

(connection? x)

Returns true if the argument is a map specifying an active connection. Otherwise, returns false.

create-collection! clj

(create-collection! collection {:capped false :size 0 :max 0})

Explicitly create a collection with the given name, which must not already exist.

Most users will not need this function, and will instead allow MongoDB to implicitly create collections when they are written to. This function exists primarily to allow the creation of capped collections, and so supports the following keyword arguments:

:capped -> boolean: if the collection is capped :size -> int: collection size (in bytes) :max -> int: max number of documents.

databases clj

(databases)

Lists database names on the MongoDB server.

db-ref clj

(db-ref ns id)

Convenience DBRef constructor.

db-ref? clj

(db-ref? x)

destroy! clj

(destroy! collection
          query
          {:from :clojure :write-concern nil :encoder nil :collation nil})

Removes map from a collection.

Required parameters: collection -> the database collection name (string, keyword, or symbol) query -> the deletion criteria using query operators (a query map), omit or pass an empty query to delete all documents in the collection

Optional parameters include: :from -> arguments (query) format (defaults to :clojure, can also be :json or :mongo) :write-concern -> set the write concern (e.g. :normal, see the write-concern-map for available options) :encoder -> set the encoder (of BSONObject to BSON) :collation -> set the collation

destroy-file! clj

(destroy-file! fs where {:from :clojure})

Removes file from gridfs. Takes a GridFS name and a query map

distinct-values clj

(distinct-values collection
                 field-name
                 {:as :clojure
                  :from :clojure
                  :where nil
                  :read-preference nil
                  :read-concern nil
                  :collation nil})

Finds the distinct values for a specified field across a collection. Returns a vector of these values, possibly formatted (according to the :as param logic).

Required parameters: collection -> the database collection field-name -> the field for which to return the distinct values (may be of a nested document; use the "dot notation" for this, e.g. "foo.bar.baz")

Optional parameters include: :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (where) format (same default/options as for :as; no effect w/o :where) :where -> the selection query to determine the subset of documents for distinct values retrieval :read-preference -> set the read preference (e.g. :primary or ReadPreference instance) :read-concern -> set the read concern (e.g. :local, see the read-concern-map for available options) :collation -> set the collation

drop-all-indexes! clj

(drop-all-indexes! coll)

Drops all indexes on the collection.

drop-coll! clj

(drop-coll! collection)

drop-database! clj

(drop-database! db-name)

Drops a database from the MongoDB server.

drop-index! clj

(drop-index! coll index)

Drops an index on the collection for the specified fields.

The index may be a vector representing the key(s) of the index (see somnium.congomongo/add-index! for the expected format).

It may also be a string/keyword, in which case it is taken to be the name of the index to be dropped.

Due to how the underlying MongoDB driver works, if you defined an index with a custom name, you MUST delete the index using that name, and not the keys.

fetch clj

(fetch collection
       {:min nil
        :read-concern nil
        :where {}
        :only []
        :cursor-type nil
        :limit 0
        :return-key? nil
        :oplog-replay? nil
        :as :clojure
        :max-await-time-ms nil
        :max-time-ms nil
        :collation nil
        :hint nil
        :one? false
        :count? false
        :read-preference nil
        :show-record-id? nil
        :no-cursor-timeout? nil
        :from :clojure
        :explain? false
        :max nil
        :comment nil
        :options []
        :partial? nil
        :sort nil
        :skip 0
        :batch-size nil})

Fetches objects from a collection. Note that MongoDB always adds the _id and _ns fields to objects returned from the database.

Required parameters: collection -> the database collection name (string, keyword, or symbol)

Optional parameters include: :one? -> will result in findOne query (defaults to false, use fetch-one as a shortcut) :count? -> will result in getCount query (defaults to false, use fetch-count as a shortcut) :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (where, sort, max, min) format (same default/options as for :as) :where -> the selection criteria using query operators (a query map) :only -> projection; a subset of fields to return for matching documents (an array of keys) :sort -> the sort criteria to apply to the query (null means an undefined order of results) :skip -> number of documents to skip :limit -> number of documents to return :batch-size -> number of documents to return per batch (by default, server chooses an appropriate) :max-time-ms -> set the maximum server execution time for this operation (default is 0, no limit) :max-await-time-ms -> set the maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query (only applies to a TailableAwait cursor type) :cursor-type -> set the cursor type (either NonTailable, Tailable, or TailableAwait) :no-cursor-timeout? -> prevent server from timing out idle cursors after an inactivity period (10 min) :oplog-replay? -> users should not set this under normal circumstances :partial? -> get partial results from a sharded cluster if one or more shards are unreachable :read-preference -> set the read preference (e.g. :primary or ReadPreference instance) :read-concern -> set the read concern (e.g. :local, see the read-concern-map for available options) :collation -> set the collation :comment -> set the comment to the query :hint -> tell the query which index to use (name (string) or [:compound :index] (seq of keys)) :max -> set the exclusive upper bound for a specific index :min -> set the minimum inclusive lower bound for a specific index :return-key? -> if true the find operation will return only the index keys in the resulting documents :show-record-id? -> set to true to add a field $recordId to the returned documents :explain? -> returns performance information on the query, instead of rows :options -> query options [:tailable :slaveok :oplogreplay :notimeout :awaitdata] (see the NOTE)

However, not all of the aforementioned optional params affect the count? mode, but only these: hint, skip, limit, max-time-ms, read-preference, read-concern, and collation.

As well, the one? mode doesn't support options, explain?, sort, limit, or hint.

NOTE: The options use a custom data format, are unnecessary and left for backward compatibility, and might be removed in the next major 'congomongo' release.

fetch-and-modify clj

fetch-and-modify! clj

(fetch-and-modify! collection
                   query
                   update
                   {:only nil
                    :upsert? false
                    :as :clojure
                    :write-concern nil
                    :max-time-ms nil
                    :collation nil
                    :remove? false
                    :from :clojure
                    :return-new? false
                    :bypass-document-validation? nil
                    :array-filters nil
                    :sort nil})

Atomically modifies and returns a single document. Selects the first document matching the query and removes/updates it. By default, the returned document does not include the modifications made on the update.

Required parameters: collection -> the database collection name (string, keyword, or symbol) query -> the selection criteria for the modification (a query map) update -> the modifications to apply to the selected document (a modifications map)

Optional parameters include: :remove? -> if true, removes the selected document :return-new? -> if true, returns the modified document rather than the original :upsert? -> if true, operation creates a new document if the query returns no documents :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (query, update, sort) format (same default/options as for :as) :only -> projection; a subset of fields to return for the selected document (an array of keys) :sort -> determines which document will be modified if the query selects multiple documents :bypass-document-validation? -> set the bypass document level validation flag :max-time-ms -> set the maximum server execution time for this operation (default is 0, no limit) :write-concern -> set the write concern (e.g. :normal, see the write-concern-map for available options) :collation -> set the collation :array-filters -> set the array filters option

NOTE: An update parameter cannot be nil unless is passed along with the :remove? true.

fetch-by-id clj

(fetch-by-id col id & options)

fetch-by-ids clj

(fetch-by-ids col ids & options)

fetch-count clj

(fetch-count col & options)

fetch-files clj

(fetch-files fs :where :from :one?)

Fetches objects from a GridFS Note that MongoDB always adds the _id and _ns fields to objects returned from the database. Optional arguments include :where -> takes a query map :from -> argument type, same options as above :one? -> defaults to false, use fetch-one-file as a shortcut

fetch-one clj

(fetch-one col & options)

fetch-one-file clj

(fetch-one-file fs & options)

get-coll clj

(get-coll collection)

Returns a DBCollection object

get-collection-read-preference clj

(get-collection-read-preference collection)

Returns the currently set read preference for a collection

get-collection-write-concern clj

(get-collection-write-concern collection)

Gets the currently set write concern for a collection.

get-db clj

(get-db conn)

Returns a DB object for the passed connection. Throws exception if there isn't one.

get-gridfs clj

(get-gridfs bucket)

Returns a GridFS object for the named bucket

get-indexes clj

(get-indexes collection :as (:clojure))

Get indexes information on a collection.

get-timestamp clj

(get-timestamp obj)

Pulls the timestamp from an ObjectId or a map with a valid ObjectId in :_id.

insert! clj

(insert! collection
         obj
         {:many? false
          :as :clojure
          :from :clojure
          :write-concern nil
          :continue-on-error? nil
          :bypass-document-validation? nil
          :encoder nil})

Inserts document(s) into a collection. If the collection does not exists on the server, then it will be created. If the new document does not contain an _id field, it will be added. Will not overwrite existing documents.

Required parameters: collection -> the database collection obj -> a document or a collection/sequence of documents to insert

Optional parameters include: :many? -> whether this will insert multiple documents (default is false) :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (obj) format (same default and options as for :as) :write-concern -> set the write concern (e.g. :normal, see the write-concern-map for available options) :continue-on-error? -> whether documents will continue to be inserted after a failure to insert one (most commonly due to a duplicate key error; default value is false) :bypass-document-validation? -> set the bypass document level validation flag :encoder -> set the encoder (of BSONObject to BSON)

NOTE: To insert as a side-effect only, specify :as as nil.

insert-file! clj

(insert-file! fs data {:filename nil :contentType nil :metadata nil})

Insert file data into a GridFS. Data should be either a File, InputStream or byte array. Options include: :filename -> defaults to nil :contentType -> defaults to nil :metadata -> defaults to nil :_id -> defaults to nil (autogenerate)

make-connection clj

(make-connection mongo-client-uri)

(make-connection db-name
                 {:instance {:host host :port port}
                  :instances instance+
                  :options mongo-options
                  :username username
                  :password password
                  :auth-source {:mechanism mechanism :source source}})

Connects to one or more MongoDB instances. Returns a connection that can be used for set-connection! and with-mongo.

This fn accepts the following parameters:

1. A db-name (string, keyword, or symbol) for the database name, and an optional args map: :instance -> a MongoDB server instance to connect to :instances -> a list of server instances to connect to (DEPRECATED) :options -> a MongoClientOptions object with various settings to control the behavior of a created MongoClient :username -> the username to authenticate with :password -> the password to authenticate with :auth-source -> the authentication source for authenticated connections in the form of a {:mechanism <auth-mechanism>, :source <auth-source>} map, where supported mechanisms = :plain, :scram-1, :scram-256.

   Each instance is a map containing values for :host and/or :port. The default values are: for host — 127.0.0.1, for port — 27017. If no instance is specified, a connection is made to a default one.

   The username and password must (and auth-source may) be supplied for authenticated connections. When auth-source is omitted, the db-name becomes mandatory (for a DB where the user is defined).

2. A mongo-client-uri (string) is also supported. It must be prefixed with "mongodb://" or "mongodb+srv://" to be distinguishable from the DB name.

   When a URI string is passed as the first parameter, the optional args are ignored.

   If username and password are specified in the URI, the connection will be authenticated.

map-reduce clj

(map-reduce collection
            mapfn
            reducefn
            out
            :out-from
            :query :query-from
            :sort :sort-from
            :limit :finalize
            :scope :scope-from
            :output :as)

Performs a map-reduce job on the server.

Mandatory arguments collection -> the collection to run the job on mapfn -> a JavaScript map function, as a String. Should take no arguments. reducefn -> a JavaScript reduce function, as a String. Should take two arguments: a key, and a corresponding array of values out -> output descriptor With MongoDB 1.8, there are many options: a collection name (String or Keyword): output is saved in the named collection, removing any data that previously existed there. Or, a configuration map: {:replace collection-name}: same as above {:merge collection-name}: incorporates results of the MapReduce with any data already in the collection {:reduce collection-name}: further reduces with any data already in the collection {:inline 1}: creates no collection, and returns the results directly

See http://www.mongodb.org/display/DOCS/MapReduce for more information, as well as the test code in congomongo_test.clj.

Optional Arguments :out-from -> indicates what form the out parameter is specified in (:clojure, :json, or :mongo). Defaults to :clojure. :query -> a query map against collection; if this is specified, the map-reduce job is run on the result of this query instead of on the collection as a whole. :query-from -> if query is supplied, specifies what form it is in (:clojure, :json, or :mongo). Defaults to :clojure. :sort -> if you want query sorted (for optimization), specify a map of sort clauses here. :sort-from -> if sort is supplied, specifies what form it is in (:clojure, :json, or :mongo). Defaults to :clojure. :limit -> the number of objects to return from a query collection (defaults to 0; that is, everything). This pertains to query, NOT the result of the overall map-reduce job! :finalize -> a finalization function (JavaScript, as a String). Should take two arguments: a key and a single value (not an array of values). :scope -> a scope object; variables in the object will be available in the global scope of map, reduce, and finalize fns. :scope-from -> if scope is supplied, specifies what form it is in (:clojure, :json, or :mongo). Defaults to :clojure. :output -> if you want the resulting documents from the map-reduce job, specify :documents; otherwise, if you want the name of the result collection as a keyword, specify :collection. Defaults to :documents. If the value of 'out' is {:inline 1}, you will get documents, regardless of what you actually put here. :as -> if :output is set to :documents, determines the form the results take (:clojure, :json, or :mongo) (has no effect if :output is set to :collection; that is always returned as a Clojure keyword)

mass-insert! clj

(mass-insert! collection
              objs
              {:as :clojure
               :from :clojure
               :write-concern nil
               :continue-on-error? nil
               :bypass-document-validation? nil
               :encoder nil})

Inserts multiple documents into a collection. If the collection does not exists on the server, then it will be created. If a new document does not contain an _id field, it will be added. Will not overwrite existing documents.

Required parameters: collection -> the database collection objs -> a collection/sequence of documents to insert

Optional parameters include: :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (obj) format (same default and options as for :as) :write-concern -> set the write concern (e.g. :normal, see the write-concern-map for available options) :continue-on-error? -> whether documents will continue to be inserted after a failure to insert one (most commonly due to a duplicate key error; default value is false) :bypass-document-validation? -> set the bypass document level validation flag :encoder -> set the encoder (of BSONObject to BSON)

NOTE: To insert as a side-effect only, specify :as as nil.

mongo-options clj

(mongo-options & options)

Returns the MongoClientOptions, populated by any specified options, e.g. (mongo-options :auto-connect-retry true).

object-id clj

(object-id s)

read-concern-map clj

read-preference clj

(read-preference preference
                 {:first-tag "value" :second-tag "second-value"}
                 {:other-tag-set "other-value"})

Creates a ReadPreference from an alias and optional tag sets. Valid aliases are :nearest, :primary, :primary-preferred, :secondary, and :secondary-preferred.

set-collection-read-preference! clj

(set-collection-read-preference! collection preference & opts)

Sets the read preference as default for a collection.

set-collection-write-concern! clj

(set-collection-write-concern! collection write-concern)

Sets this write concern as default for a collection.

set-connection! clj

(set-connection! connection)

Makes the passed connection an active one. Takes a connection created by the make-connection.

NOTE: When with-mongo and set-connection! interact, last one wins.

set-database! clj

(set-database! db-name)

Atomically alters the current database.

set-options! clj

set-read-preference clj

(set-read-preference connection preference)

Sets the read preference on the connection (you may supply a ReadPreference or a valid alias).

set-write-concern clj

(set-write-concern connection setting)

Sets the write concern on the connection. Setting is a key in the write-concern-map above.

stream-from clj

(stream-from fs file)

Returns an InputStream from the GridFS file specified

StringNamed clj protocol

named clj

(named s)

convenience for interchangeably handling keywords, symbols, and strings

update! clj

(update! collection
         old
         new
         {:upsert? true
          :encoder nil
          :as :clojure
          :write-concern nil
          :collation nil
          :from :clojure
          :multiple? false
          :bypass-document-validation? nil
          :array-filters nil})

Alters/inserts a map in a collection. Overwrites existing objects. The shortcut forms need a map with valid _id and _ns fields or a collection and a map with a valid _id field.

Required parameters: collection -> the database collection name (string, keyword, or symbol) query -> the selection criteria for the update (a query map) update -> the modifications to apply (a modifications map)

Optional parameters include: :upsert? -> do upsert, i.e. insert if document not present (default is true) :multiple? -> whether this will update all documents matching the query filter (default is false) :as -> return value format (defaults to :clojure, can also be :json or :mongo) :from -> arguments (query, update) format (same default and options as for :as) :write-concern -> set the write concern (e.g. :normal, see the write-concern-map for available options) :bypass-document-validation? -> set the bypass document level validation flag :encoder -> set the encoder (of BSONObject to BSON) :collation -> set the collation :array-filters -> set the array filters option

with-db clj macro

(with-db db-name & body)

Makes the db-name an active database in the enclosing scope.

NOTE: When with-db and set-database! interact, last one wins.

with-default-query-options clj macro

(with-default-query-options options & body)

Sets options as the default query options in the enclosing scope.

These options override a function-specific default parameter values, but get overridden themselves by the params passed to a function.

NOTE: So far, only fetch and fetch-and-modify fns support these options.

with-mongo clj macro

(with-mongo connection & body)

Makes the passed connection an active one in the enclosing scope.

NOTE: When with-mongo and set-connection! interact, last one wins.

with-ref-fetching clj

(with-ref-fetching fetcher)

Returns a decorated fetcher fn which eagerly loads db-refs.

write-concern-map clj

write-file-to clj

(write-file-to fs file out)

Writes the data stored for a file to the supplied output, which should be either an OutputStream, File, or the String path for a file.