somnium.congomongo — circleci/congomongo 2.2.3-SNAPSHOT

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).

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

aggregate clj

(aggregate coll op & ops {:from :clojure :to :clojure})

Executes a pipeline of operations using the Aggregation Framework. Returns map {:serverUsed ... :result ... :ok ...} :serverUsed - string representing server address :result - the result of the aggregation (if successful) :ok - 1.0 for success Requires MongoDB 2.2!

calculate-query-options clj

(calculate-query-options options)

Calculates the cursor's query option from a list of options

close-connection clj

(close-connection conn)

Closes the connection, 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 cmd {:options nil :from :clojure :to :clojure})

Executes a database command.

connection? clj

(connection? x)

Returns truth if the argument is a map specifying an active connection.

create-collection! clj

(create-collection! collection :capped :size :max)

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)

List databases on the mongo server

db-ref clj

(db-ref ns id)

Convenience DBRef constructor.

db-ref? clj

(db-ref? x)

destroy! clj

(destroy! collection where {:from :clojure :write-concern nil})

Removes map from collection. Takes a collection name and a query map

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 key :where :from :as)

Queries a collection for the distinct values of a given key. Returns a vector of the values by default (but see the :as keyword argument). The key (a String) can refer to a nested object, using dot notation, e.g., "foo.bar.baz".

Optional arguments include :where -> a query object. If supplied, distinct values from the result of the query on the collection (rather than from the entire collection) are returned. :from -> specifies what form a supplied :where query is in (:clojure, :json, or :mongo). Defaults to :clojure. Has no effect if there is no :where query. :as -> results format (:clojure, :json, or :mongo). Defaults to :clojure.

drop-all-indexes! clj

(drop-all-indexes! coll)

Drops all indexes from a collection

drop-coll! clj

(drop-coll! collection)

drop-database! clj

(drop-database! title)

drops a database from the mongo server

drop-index! clj

(drop-index! coll index)

Drops an index on the collection for the specified fields.

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 or Keyword, in which case it is taken to be the name of the index to be deleted.

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
       :where :only
       :limit :skip
       :as :from
       :one? :count?
       :sort :hint
       :explain? :options
       :max-time-ms :read-preferences)

Fetches objects from a collection. Note that MongoDB always adds the _id and _ns fields to objects returned from the database. Optional arguments include :where -> takes a query map :only -> takes an array of keys to retrieve :as -> what to return, defaults to :clojure, can also be :json or :mongo :from -> argument type, same options as above :skip -> number of records to skip :limit -> number of records to return :one? -> defaults to false, use fetch-one as a shortcut :count? -> defaults to false, use fetch-count as a shortcut :explain? -> returns performance information on the query, instead of rows :sort -> sort the results by a specific key :options -> query options [:tailable :slaveok :oplogreplay :notimeout :awaitdata] :hint -> tell the query which index to use (name (string) or [:compound :index] (seq of keys)) :read-preferences -> read preferences (e.g. :primary or ReadPreference instance) :max-time-ms -> set the maximum execution time for operations

fetch-and-modify clj

(fetch-and-modify collection
                  where
                  update
                  {:only nil
                   :sort nil
                   :remove? false
                   :return-new? false
                   :upsert? false
                   :max-time-ms 0
                   :from :clojure
                   :as :clojure})

Finds the first document in the query and updates it. Parameters: coll -> the collection where -> query to match update -> update to apply :only -> fields to be returned :sort -> sort to apply before picking first document :remove? -> if true, document found will be removed :return-new? -> if true, the updated document is returned, otherwise the old document is returned (or it would be lost forever) :upsert? -> do upsert (insert if document not present) :max-time-ms -> set the maximum execution time for operations

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 the current 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 index information on 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! coll obj {:many false :from :clojure :to :clojure :write-concern nil})

Inserts a map into collection. Will not overwrite existing maps. Takes optional from and to keyword arguments. To insert as a side-effect only specify :to 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
                 :instances [{:host host :port port}]
                 :options mongo-options
                 :username username
                 :password password
                 :auth-source {:mechanism mechanism :source source})

Connects to one or more mongo instances, returning a connection that can be used with set-connection! and with-mongo.

Each instance is a map containing values for :host and/or :port.

May be called with database name and optionally: :instances - a list of server instances to connect to :options - a MongoClientOptions object :username - the username to authenticate with :password - the password to authenticate with :auth-source - the authentication source for authenticated connections in form: {:mechanism mechanism :source source} Supported authentication mechanisms: :plain :scram-1 :scram-256

If instances are not specified a connection is made to 127.0.0.1:27017

Username and password must be supplied for authenticated connections.

A MongoClientURI string is also supported and must be prefixed with mongodb:// or mongodb+srv://. If username and password are specified 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 finalizaton 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 functions. :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! coll objs {:from :clojure :to :clojure})

mongo-options clj

(mongo-options & options)

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

object-id clj

(object-id s)

query-option-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 connection active. Takes a connection created by make-connection.

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

set-database! clj

(set-database! title)

atomically alters the current database

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 :multiple false :as :clojure :from :clojure :write-concern 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.

with-db clj macro

(with-db dbname & body)

Make dbname the active database in the enclosing scope.

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

with-default-query-options clj macro

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

with-mongo clj macro

(with-mongo conn & body)

Makes conn the active connection in the enclosing scope.

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.