com.timezynk.mongo — com.timezynk/mongo 0.9.13

A functional Clojure wrapper for the modern Java MongoDB API.

aggregate clj

(aggregate <collection> & <pipeline>)

MongoDB aggregation.

Parameter	Description
collection	keyword/string Collection name.
pipeline	The request pipeline queries.

Returns

Aggregation result.

Examples

(aggregate :users
           {:$match {:age {:$gte 20}}}
           {:$project {:_id 0
                       :name 1}})

close-connection! clj

(close-connection! conn)

collation clj

(collation <locale>
           &
           :alternate [:non-ignorable :shifted]
           :backwards? <boolean>
           :case-first [:lower :off :upper]
           :case-level? <boolean>
           :max-variable [:punct :space]
           :normalization? <boolean>
           :numeric-ordering? <boolean>
           :strength [:identical :primary :quaternary :secondary :tertiary])

Create collation.

Parameter	Description
locale	string The two-letter ICU locale string.
:alternate	optional enum Should whitespace and punctuation be considered as base characters for purposes of comparison?
	:non-ignorable Whitespace and punctuation are considered base characters.
	:shifted Whitespace and punctuation are not considered base characters and are only distinguished at strength levels greater than 3.
:backwards?	optional boolean Whether strings with diacritics sort from back of the string, such as with some French dictionary ordering. Default is false.
:case-first	optional enum Sort order of case differences during tertiary level comparisons.
	:lower Uppercase sorts before lowercase.
	:upper Lowercase sorts before uppercase.
	:off Default value. Similar to :lower with slight differences.
:case-level?	optional boolean Flag that determines whether to include case comparison at strength level 1 or 2.
:max-variable	optional enum Which characters are considered ignorable when :alternate = :shifted? Has no effect if :alternate = :non-ignorable.
	:punct Both whitespace and punctuation are ignorable and not considered base characters.
	:space Whitespace is ignorable and not considered to be base characters.
:normalization?	optional boolean Check if text requires normalization and to perform normalization. Default is false.
:numeric-ordering?	optional boolean Compare numeric strings as numbers or as strings. Default is false.
:strength	optional enum The level of comparison to perform.
	:identical Limited for specific use case of tie breaker.
	:primary Collation performs comparisons of the base characters only, ignoring other differences such as diacritics and case.
	:secondary Collation performs comparisons up to secondary differences, such as diacritics. That is, collation performs comparisons of base characters (primary differences) and diacritics (secondary differences). Differences between base characters takes precedence over secondary differences.
	:tertiary Collation performs comparisons up to tertiary differences, such as case and letter variants. That is, collation performs comparisons of base characters (primary differences), diacritics (secondary differences), and case and variants (tertiary differences). Differences between base characters takes precedence over secondary differences, which takes precedence over tertiary differences. Default level.
	:quaternary Limited for specific use case to consider punctuation when levels 1-3 ignore punctuation or for processing Japanese text.

For more details, see the manual page on collation.

Returns

The collation object.

Examples

(collation)

collection-info clj

(collection-info coll)

List full info of collection.

Parameter	Description
name	keyword/string Collection name.

create-collection! clj

(create-collection! <name>
                    &
                    :collation
                    <collation
                    object>
                    :level <integer>
                    :schema {}
                    :validation {})

Create collection.

Parameter	Description
name	keyword/string Collection name.
:collation	optional collation object The collation of the collection.
:schema	optional map The schema validation map.
:validation	optional map Validation logic outside of the schema.
:level	optional enum Validaton level:
	:strict Apply validation rules to all inserts and all updates. Default value.
	:moderate Applies validation rules to inserts and to updates on existing valid documents.
	:off No validation for inserts or updates.

Returns

The collection object.

Examples

; Collection with exactly one required field `name` of type `string`:
(create-collection! :users :schema {:name (string)})

; Collection where each document can have either a `name` field or an `address` field, but not both:
(create-collection! :users :validation {:$or [{:name {:$ne nil} :address {:$exists 0}}
                                              {:name {:$exists 0} :address {:$ne nil}}]})

create-connection! clj

(create-connection! <uri>
                    &
                    :retry-writes? <boolean>
                    :write-concern [:acknowledged :unacknowledged :journaled
                                    :majority :w1 :w2 :w3])

Create a connection object.

Parameter	Description
uri	string Database location.
:retry-writes?	optional boolean Sets whether writes should be retried if they fail due to a network error. Default is false.
:write-concern	optional enum Set write concern:
	:acknowledged Write operations that use this write concern will wait for acknowledgement. Default.
	:majority Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation.
	:unacknowledged Write operations that use this write concern will return as soon as the message is written to the socket.
	:w1 Write operations that use this write concern will wait for acknowledgement from a single member.
	:w2 Write operations that use this write concern will wait for acknowledgement from two members.
	:w3 Write operations that use this write concern will wait for acknowledgement from three members.

Returns

The connection object.

Examples

; Create a connection with default options
(connection "mongodb://localhost:27017")

; Create a custom connection
(connection "mongodb://localhost:27017" :retry-writes true :write-concern :w2)

create-index! clj

(create-index! <collection>
               <keys>
               &
               :collation
               <collation
               object>
               :background? <boolean>
               :name <string>
               :filter {}
               :sparse? <boolean>
               :unique? <boolean>)

Create an index for a collection.

Parameter	Description
collection	keyword/string Collection name.
keys	map/list(keyword/string) A document or a list of keywords or strings.
:collation	optional collation object Collation of index.
:background?	optional boolean Create the index in the background. Default false.
:name	optional string A custom name for the index.
:filter	optional map A partial-filter-expression for the index.
:sparse?	optional boolean Don't index null values. Default false.
:unique?	optional boolean Index values must be unique. Default false.

Returns

The index name.

Examples

; Index over field-1 in descending order, field-2 as hashed
(create-index! :coll {:field-1 -1 :field-2 "hashed"})

; Shorthand for indexing over fields in ascending order
(create-index! :coll [:field-1 :field-2])

; Only flagged documents are indexed and searchable
(create-index! :coll [:field-1] :filter {:flag-field true})

delete! clj

(delete! <collection> <query> & :collation <collation object> :hint {})

Delete matching documents.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
:collation	optional collation object Collation used.
:hint	optional map Indexing hint.

Returns

{:deleted-count <number of matching documents>}

delete-one! clj

(delete-one! <collection> <query> & :collation <collation object> :hint {})

Delete first matching document.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
:collation	optional collation object Collation used.
:hint	optional map Indexing hint.

Returns

{:deleted-count <0 or 1>}

delete-one-by-id! clj

(delete-one-by-id! coll id & options)

drop-collection! clj

(drop-collection! coll)

drop-index! clj

(drop-index! coll index)

fetch clj

(fetch <collection>)

(fetch <collection>
       <query>
       &
       :collation
       <collation
       object>
       :limit <count>
       :only {}
       :skip <count>
       :sort {})

Fetch documents from collection.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
:collation	optional collation object Collation used.
:limit	optional int Number of documents to fetch.
:only	optional map/list A map/list of fields to include or exclude.
:skip	optional int Number of documents to skip before fetching.
:sort	optional map A MongoDB map of sorting criteria.

Returns

A lazy sequence of matching documents.

Examples

; Fetch five documents from collection :users
(fetch :users {} :limit 5)

fetch-and-delete-one! clj

(fetch-and-delete-one! coll query & options)

fetch-and-delete-one-by-id! clj

(fetch-and-delete-one-by-id! coll id & options)

fetch-and-replace-one! clj

(fetch-and-replace-one! coll query doc & options)

fetch-and-replace-one-by-id! clj

(fetch-and-replace-one-by-id! coll id doc & options)

fetch-and-set-by-id! clj

(fetch-and-set-by-id! coll id update & options)

fetch-and-set-one! clj

(fetch-and-set-one! coll query update & options)

Shorthand for fetch-and-update-one! with a single :$set modifier.

Examples

(fetch-and-set-one! :coll {} {:a 1})

translates to:

(fetch-and-update-one! :coll {} {:$set {:a 1}})

fetch-and-update-by-id! clj

(fetch-and-update-by-id! coll id update & options)

fetch-and-update-one! clj

(fetch-and-update-one! <collection>
                       <query>
                       &
                       :return-new?
                       <boolean>
                       :upsert?
                       <boolean>
                       :collation
                       <collation
                       object>
                       :only {}
                       :hint {}
                       :sort {})

Update first matching document.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
:return-new?	optional boolean Return the updated document? Default if false.
:upsert?	optional boolean If no document is found, create a new one. Default is false.
:collation	optional collation object Collation used.
:only	optional map A MongoDB map of fields to include or exclude.
:hint	optional map Indexing hint.
:sort	optional map A MongoDB map of sorting criteria.

Returns

A single document or nil.

fetch-by-id clj

(fetch-by-id <collection> <id> & :only {})

Fetch a single document by its id.

Parameter	Description
collection	keyword/string The collection.
id	ObjectId/string The id. A string will be converted to an ObjectId.
:only	optional map A MongoDB map of fields to include or exclude.

Returns

A single document or nil.

fetch-count clj

(fetch-count <collection>)

(fetch-count <collection> <query>)

Count the number of documents returned.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.

Returns

Number of matching documents.

fetch-one clj

(fetch-one <collection>)

(fetch-one <collection>
           <query>
           &
           :collation
           <collation
           object>
           :only {}
           :skip <count>
           :sort {})

Return only the first document retrieved.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
:collation	optional collation object Collation used.
:only	optional map A MongoDB map of fields to include or exclude.
:skip	optional int Number of documents to skip before fetching.
:sort	optional map A MongoDB map of sorting criteria.

Returns

A single document or nil.

insert! clj

(insert! <collection>
         <document>
         &
         :write-concern
         [:acknowledged :unacknowledged :journaled :majority :w1 :w2 :w3])

(insert! <collection>
         <document-list>
         &
         :write-concern
         [:acknowledged :unacknowledged :journaled :majority :w1 :w2 :w3])

Insert one document or a list thereof in a collection. Inserting a list is atomic.

Parameter	Description
collection	keyword/string The collection.
document	map A document.
document-list	list(map) A list of documents.
:write-concern	optional enum Set write concern:
	:acknowledged Write operations that use this write concern will wait for acknowledgement. Default.
	:majority Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation.
	:unacknowledged Write operations that use this write concern will return as soon as the message is written to the socket.
	:w1 Write operations that use this write concern will wait for acknowledgement from a single member.
	:w2 Write operations that use this write concern will wait for acknowledgement from two members.
	:w3 Write operations that use this write concern will wait for acknowledgement from three members.

Returns

The document/s with _id fields, either a single document or a lazy sequence.

Examples

(insert! :users {:name "Alice"})

(insert! :users [{:name "Alice"} {:name "Bob"}])

insert-one! clj

(insert-one! coll doc & options)

This is identical to insert!, except if payload is nil, return nil instead of throwing exception. Use this function when the payload is expected to be a nil-able document.

list-collection-names clj

(list-collection-names)

List keyworded names of all collections in database.

list-collections clj

(list-collections)

List full info of all collections in database.

list-databases clj

(list-databases)

List databases for this connection.

Returns

A lazy sequence of database objects.

list-indexes clj

(list-indexes coll)

modify-collection! clj

(modify-collection! <name>
                    &
                    :collation
                    <collation
                    object>
                    :level <integer>
                    :schema {}
                    :validation {})

Make updates to a collection.

Parameter	Description
name	keyword/string Collection name.
:name	optional keyword/string New name.
:collation	optional collation object The collation of the collection.
:schema	optional map The schema validation map.
:validation	optional map Validation logic outside of the schema.
:level	optional enum Validaton level:
	:strict Apply validation rules to all inserts and all updates. Default value.
	:moderate Applies validation rules to inserts and to updates on existing valid documents.
	:off No validation for inserts or updates.
:validate?	optional boolean Ensure that existing documents in the collection conform to the new schema or validation. Default false.

Returns

The collection object.

Examples

(modify-collection! :coll :name :coll-2)

replace-one! clj

(replace-one! <collection>
              <query>
              <document>
              &
              :upsert?
              <boolean>
              :collation
              <collation
              object>
              :hint
              {})

Replace a single document.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
document	map The new document.
:upsert?	optional boolean If no document is found, create a new one. Default is false.
:collation	optional collation object Collation used.
:hint	optional map Indexing hint.

Returns

{:matched-count <0 or 1>
 :modified-count <0 or 1>}

replace-one-by-id! clj

(replace-one-by-id! coll id doc & options)

set! clj

(set! coll query update & options)

Shorthand for update! with a single :$set modifier.

Examples

(set! :coll {} {:a 1})

translates to:

(update! :coll {} {:$set {:a 1}})

set-by-id! clj

(set-by-id! coll id update & options)

set-one! clj

(set-one! coll query update & options)

Shorthand for update-one! with a single :$set modifier.

Examples

(set-one! :coll {} {:a 1})

translates to:

(update-one! :coll {} {:$set {:a 1}})

transaction clj macro

(transaction & body)

Functionally perform a transaction. Encapsulated database requests are queued and then atomically executed when the function goes out of scope.

Returns

The result of the last encapsulated expression.

Examples

(transaction
 (insert! :users {:name "My Name"})
 (fetch! :users))

update! clj

(update! <collection>
         <query>
         <update>
         &
         :upsert?
         <boolean>
         :collation
         <collation
         object>
         :hint {}
         :write-concern [:acknowledged :unacknowledged :journaled :majority :w1
                         :w2 :w3])

Update matching documents.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
update	map A valid update document.
:upsert?	optional boolean If no document is found, create a new one. Default is false.
:collation	optional collation object Collation used.
:hint	optional map/list Indexing hint.
:write-concern	optional enum Set write concern:
	:acknowledged Write operations that use this write concern will wait for acknowledgement. Default.
	:majority Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation.
	:unacknowledged Write operations that use this write concern will return as soon as the message is written to the socket.
	:w1 Write operations that use this write concern will wait for acknowledgement from a single member.
	:w2 Write operations that use this write concern will wait for acknowledgement from two members.
	:w3 Write operations that use this write concern will wait for acknowledgement from three members.

Returns

{:matched-count <number of matching documents>
 :modified-count <number of modified documents>}

Examples

(update!)

update-by-id! clj

(update-by-id! coll id update & options)

update-one! clj

(update-one! <collection>
             <query>
             <update>
             &
             :upsert?
             <boolean>
             :collation
             <collation
             object>
             :hint {}
             :write-concern [:acknowledged :unacknowledged :journaled :majority
                             :w1 :w2 :w3])

Update first matching document.

Parameter	Description
collection	keyword/string The collection.
query	map A standard MongoDB query.
update	map/list A valid update document or pipeline.
:upsert?	optional boolean If no document is found, create a new one. Default is false.
:collation	optional collation object Collation used.
:hint	optional map/list Indexing hint.
:write-concern	optional enum Set write concern:
	:acknowledged Write operations that use this write concern will wait for acknowledgement. Default.
	:majority Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation.
	:unacknowledged Write operations that use this write concern will return as soon as the message is written to the socket.
	:w1 Write operations that use this write concern will wait for acknowledgement from a single member.
	:w2 Write operations that use this write concern will wait for acknowledgement from two members.
	:w3 Write operations that use this write concern will wait for acknowledgement from three members.

Returns

{:matched-count <0 or 1>
 :modified-count <0 or 1>}

Examples

(update-one!)

with-codecs clj macro

(with-codecs <codecs> <bson-types> & <body>)

Functionally add or change codecs. Reverts to earlier settings when leaving scope.

Parameter	Description
codecs	list A list of codec objects.
bson-types	map A map of Bson types and their corresponding Java classes.
body	Encapsulated program calling the database.

with-database clj macro

(with-database <database> & <body>)

Functionally set up or change database. Reverts to earlier settings when leaving scope.

Parameter	Description
database	string Name of database to use.
body	Encapsulated program calling the database.

Returns

The result of the last encapsulated expression.

Examples

(with-database "my-database-2"
  (insert! :users {:name "My Name"})
  (fetch! :users))

with-mongo clj macro

(with-mongo <uri> & <body>)

(with-mongo <connection> & <body>)

Functionally set up or change mongodb connection. Reverts to earlier settings when leaving scope.

Parameter	Description
uri	string Connection string. See the API documentation for more details.
connection	Connection A connection object.
body	Encapsulated program utilizing the connection.

Returns

The result of the last encapsulated expression.

Examples

(with-mongo "mongodb://localhost:27017/my-database"
  (insert! :users {:name "My Name"})
  (fetch! :users))