com.timezynk.mongo — com.timezynk/mongo 0.10.2

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 macro

(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 object.

Parameter	Description
locale	string The two-letter ICU locale string.
:alternate	optional keyword 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 keyword 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 keyword 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 keyword 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 macro

(create-collection! <name>
                    &
                    :collation
                    <collation
                    object>
                    :level [:strict :moderate :off]
                    :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 keyword 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 macro

(create-connection! <uri>
                    &
                    :retry-reads? <boolean>
                    :retry-writes? <boolean>
                    :read-concern [:available :default :linearizable :local
                                   :majority :snapshot]
                    :write-concern [:acknowledged :journaled :majority
                                    :unacknowledged :w1 :w2 :w3])

Create a connection object.

Parameter	Description
uri	string Database location.
:retry-reads?	optional boolean Sets whether reads should be retried if they fail due to a network error.
:retry-writes?	optional boolean Sets whether writes should be retried if they fail due to a network error.
:read-concern	optional keyword enum Set read concern:
	:available The query returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
	:default Sets the default concern, which is usually local
	:linearizable The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation.
	:local The query returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
	:majority The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
	:snapshot Returns majority-committed data as it appears across shards from a specific single point in time in the recent past.
	Read more about read concerns.
:write-concern	optional keyword enum Set write concern:
	:acknowledged Write operations that use this write concern will wait for acknowledgement. Default.
	:journaled Wait for the server to group commit to the journal file on disk.
	:majority Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation. Usually the default option.
	:unacknowledged Return as soon as the message is written to the socket.
	:w1 Wait for acknowledgement from a single member.
	:w2 Wait for acknowledgement from two members.
	:w3 Wait for acknowledgement from three members.
	Read more about write concerns.

Returns

The connection object.

Examples

; Create a connection with default options
(create-connection! "mongodb://localhost:27017/my-database")

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

create-index! clj macro

(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})

database-name clj

(database-name)

Get the name of the currently active database.

delete! clj macro

(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-by-id! clj

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

delete-file! clj macro

(delete-file! id)

(delete-file! bucket id)

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>}

distinct clj macro

(distinct <collection> <field>)

(distinct <collection> <field> <query> & :validate? <boolean>)

Fetch distinct values from a particular field.

Parameter	Description
collection	keyword/string The collection.
field	keyword/string A field in the collection.
query	map A standard MongoDB query.
:validate?	optional boolean The field must be part of the collection schema. Default false.

Returns

A lazy sequence of distinct values.

Examples

(insert! :coll-1 [{:a 1} {:a 1} {:a 2}])
(distinct :coll-1 :a) ; Returns [1 2]
(distinct :coll-1 :b) ; Returns []

(create-collection! :coll-2 :schema {:a (map {:b (integer)})})
(insert! :coll-2 [{:a {:b 1}} {:a {:b 2}}])
(distinct :coll-2 :a.b {} :validate? true) ; Returns [1 2]
(distinct :coll-2 :a.a {} :validate? true) ; Returns IllegalArgumentException

download-file clj macro

(download-file bucket file & {:as options})

drop-collection! clj

(drop-collection! coll)

drop-index! clj

(drop-index! coll index)

fetch clj macro

(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 integer Number of documents to fetch.
:only	optional map/list A map/list of fields to include or exclude.
:skip	optional integer 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-by-id! clj

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

fetch-and-delete-one! clj

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

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

(fetch-and-replace-by-id! coll id doc & {:as options})

fetch-and-replace-one! clj macro

(fetch-and-replace-one! coll query doc & {:as options})

fetch-and-set-by-id! clj macro

(fetch-and-set-by-id! coll id update & {:as options})

fetch-and-set-one! clj macro

(fetch-and-set-one! coll query update & {:as 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 & {:as options})

fetch-and-update-one! clj macro

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

(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.
: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 macro

(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 integer Number of documents to skip before fetching.
:sort	optional map A MongoDB map of sorting criteria.

Returns

A single document or nil.

file-info clj macro

(file-info)

(file-info <bucket>)

(file-info <bucket>
           <query>
           &
           :collation
           <collation
           object>
           :limit <count>
           :only {}
           :skip <count>
           :sort {})

Fetch files.

Parameter	Description
bucket	keyword/string/nil The bucket name. Can be nil to get the default database bucket.
query	map A standard MongoDB query.
:collation	optional collation object Collation used.
:limit	optional integer Number of documents to fetch.
:skip	optional integer Number of documents to skip before fetching.
:sort	optional map/list A map/list of sorting criteria.

Returns

A lazy sequence of matching documents.

insert! clj macro

(insert! <collection> <document>)

(insert! <collection> <document-list>)

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.

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 macro

(insert-one! coll doc)

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 macro

(modify-collection! <name>
                    &
                    :collation
                    <collation
                    object>
                    :level
                    [:strict :moderate :off]
                    :name
                    <new
                    name>
                    :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 keyword enum Validation 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-by-id! clj macro

(replace-by-id! coll id doc & {:as options})

replace-one! clj macro

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

run-command clj

(run-command <command> <parameter> & <options>)

Run custom commands.

Parameter	Description
command	keyword The command to be executed.
parameter	The parameter fo the command. Typically just the number 1.
options	Key-value pairs of optional parameters specific to the command.

Options are not checked for correctness.

Returns

Results vary depending on the command.

Examples

(run-command :collStats "coll-name" :scale 1)

server-status clj

(server-status
  &
  :asserts
  :batchedDeletes :bucketCatalog
  :catalogStats :changeStreamPreImages
  :collectionCatalog :connections
  :defaultRWConcern :electionMetrics
  :extra_info :featureCompatibilityVersion
  :flowControl :globalLock
  :hedgingMetrics :indexBuilds
  :indexBulkBuilder :indexStats
  :internalTransactions :locks
  :logicalSessionRecordCache :mem
  :metrics :mirroredReads
  :network :opLatencies
  :opWorkingTime :opReadConcernCounters
  :opWriteConcernCounters :opcounters
  :opcountersRepl :oplogTruncation
  :planCache :queryAnalyzers
  :querySettings :queryStats
  :queues :readConcernCounters
  :readPreferenceCounters :repl
  :scramCache :security
  :shardedIndexConsistency :shardingStatistics
  :shardSplits :storageEngine
  :tcmalloc :tenantMigrations
  :trafficRecording :transactions
  :transportSecurity :twoPhaseCommitCoordinator
  :watchdog :wiredTiger)

Fetch information about the server.

Parameter	Description
options	optional keywords Fields to be included in the result.
	When providing options, fields not included will be excluded from result.
	Not providing any option will yield a full result, including all fields.

Options are not checked for correctness. Valid options may vary depending on the MongoDB version.

Returns

The status object.

Examples

(server-status :asserts :queues)

(server-status :assets) ; Runs fine, but will only return the minimal status information.

set! clj macro

(set! coll query update & {:as 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 macro

(set-by-id! coll id update & {:as options})

set-one! clj macro

(set-one! coll query update & {:as 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)

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 macro

(update! <collection>
         <query>
         <update>
         &
         :upsert?
         <boolean>
         :collation
         <collation
         object>
         :hint
         {})

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.

Returns

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

Examples

(update!)

update-by-id! clj macro

(update-by-id! coll id update & {:as options})

update-one! clj macro

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

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.

Returns

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

Examples

(update-one!)

upload-file! clj macro

(upload-file! bucket file & {:as options})

with-codecs clj macro

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

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.

Returns

Example

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

with-read-concern clj macro

(with-read-concern <read-concern> & <body>)

Set read concern of current active database. Reverts to earlier settings when leaving scope.

Parameter	Description
:read-concern	optional keyword enum Set read concern:
	:available The query returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
	:default Sets the default concern, which is usually local
	:linearizable The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation.
	:local The query returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
	:majority The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
	:snapshot Returns majority-committed data as it appears across shards from a specific single point in time in the recent past.
	Read more about read concerns.

with-write-concern clj macro

(with-write-concern <write-concern> & <body>)

Set write concern of current active database. Reverts to earlier settings when leaving scope.

Parameter	Description
:write-concern	optional keyword enum Set write concern:
	:acknowledged Write operations that use this write concern will wait for acknowledgement. Default.
	:journaled Wait for the server to group commit to the journal file on disk.
	:majority Exceptions are raised for network issues, and server errors; waits on a majority of servers for the write operation. Usually the default option.
	:unacknowledged Return as soon as the message is written to the socket.
	:w1 Wait for acknowledgement from a single member.
	:w2 Wait for acknowledgement from two members.
	:w3 Wait for acknowledgement from three members.
	Read more about write concerns.