A functional Clojure wrapper for the modern Java MongoDB API.
A functional Clojure wrapper for the modern Java MongoDB API.
(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}})
MongoDB aggregation. | Parameter | Description | | --- | --- | | `collection` | `keyword/string` Collection name. | | `pipeline` | The request pipeline queries. | **Returns** Aggregation result. **Examples** ```Clojure (aggregate :users {:$match {:age {:$gte 20}}} {:$project {:_id 0 :name 1}}) ```
(close-connection! conn)
(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)
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](https://www.mongodb.com/docs/v5.3/reference/collation/). **Returns** The collation object. **Examples** ```Clojure (collation) ```
(collection-info coll)
List full info of collection.
Parameter | Description |
---|---|
name | keyword/string Collection name. |
List full info of collection. | Parameter | Description | | --- | --- | | `name` | `keyword/string` Collection name. |
(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 {:$exists 1} :address {:$exists 0}}
{:name {:$exists 0} :address {:$exists 1}}]})
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** ```Clojure ; 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 {:$exists 1} :address {:$exists 0}} {:name {:$exists 0} :address {:$exists 1}}]}) ```
(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 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** ```Clojure ; 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! <collection>
<keys>
&
:background? <boolean>
:name <string>
:partial-filter-expression {}
: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. |
:background? | optional boolean Create the index in the background. Default false . |
:name | optional string A custom name for the index. |
:partial-filter-expression | optional map A filter expression for the index. |
:sparse? | optional boolean Allow null values. Default false . |
:unique? | optional boolean Index values must be unique. Default false . |
Returns
The index name.
Examples
(create-index!)
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. | | `:background?` | `optional boolean` Create the index in the background. Default `false`. | | `:name` | `optional string` A custom name for the index. | | `:partial-filter-expression` | `optional map` A filter expression for the index. | | `:sparse?` | `optional boolean` Allow null values. Default `false`. | | `:unique?` | `optional boolean` Index values must be unique. Default `false`. | **Returns** The index name. **Examples** ```Clojure (create-index!) ```
(delete! <collection> <query>)
Delete matching documents.
Parameter | Description |
---|---|
collection | keyword/string The collection. |
query | map A standard MongoDB query. |
Returns
{:deleted-count <number of matching documents>}
Delete matching documents. | Parameter | Description | | --- | --- | | `collection` | `keyword/string` The collection. | | `query` | `map` A standard MongoDB query. | **Returns** ```Clojure {:deleted-count <number of matching documents>} ```
(delete-one! <collection> <query>)
Delete first matching document.
Parameter | Description |
---|---|
collection | keyword/string The collection. |
query | map A standard MongoDB query. |
Returns
{:deleted-count <0 or 1>}
Delete first matching document. | Parameter | Description | | --- | --- | | `collection` | `keyword/string` The collection. | | `query` | `map` A standard MongoDB query. | **Returns** ```Clojure {:deleted-count <0 or 1>} ```
(drop-collection! coll)
(drop-index! coll index)
(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 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 lazy sequence of matching documents.
Examples
; Fetch five documents from collection :users
(fetch :users {} :limit 5)
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` 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 lazy sequence of matching documents. **Examples** ```Clojure ; Fetch five documents from collection :users (fetch :users {} :limit 5) ```
(fetch-and-delete-one! coll query)
(fetch-and-replace-one! coll query doc & options)
(fetch-and-update-one! <collection>
<query>
&
:return-new? <boolean>
:upsert? <boolean>)
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 . |
Returns
A single document or nil.
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`. | **Returns** A single document or nil.
(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.
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 <collection>)
(fetch-one <collection> <query>)
Return only the first document retrieved.
Parameter | Description |
---|---|
collection | keyword/string The collection. |
query | map A standard MongoDB query. |
Returns
A single document or nil
.
Return only the first document retrieved. | Parameter | Description | | --- | --- | | `collection` | `keyword/string` The collection. | | `query` | `map` A standard MongoDB query. | **Returns** A single document or `nil`.
(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 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** ```Clojure (insert! :users {:name "Alice"}) (insert! :users [{:name "Alice"} {:name "Bob"}]) ```
(list-collection-names)
List keyworded names of all collections in database.
List keyworded names of all collections in database.
(list-collections)
List full info of all collections in database.
List full info of all collections in database.
(list-databases)
List databases for this connection.
Returns
A lazy sequence of database objects.
List databases for this connection. **Returns** A lazy sequence of database objects.
(list-indexes coll)
(modify-collection! <name> & :name <string>)
Make updates to a collection.
Parameter | Description |
---|---|
name | keyword/string Collection name. |
:name | optional keyword/string New name. |
Returns
The collection object.
Examples
(modify-collection! :coll :name :coll-2)
Make updates to a collection. | Parameter | Description | | --- | --- | | `name` | `keyword/string` Collection name. | | `:name` | `optional keyword/string` New name. | **Returns** The collection object. **Examples** ```Clojure (modify-collection! :coll :name :coll-2) ```
(replace-one! <collection> <query> <document> & :upsert? <boolean>)
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 . |
Returns
{:matched-count <0 or 1>
:modified-count <0 or 1>}
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`. | **Returns** ```Clojure {:matched-count <0 or 1> :modified-count <0 or 1>} ```
(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))
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** ```Clojure (transaction (insert! :users {:name "My Name"}) (fetch! :users)) ```
(update! <collection> <query> <update> & :upsert? <boolean>)
Update matching documents.
Parameter | Description |
---|---|
collection | keyword/string The collection. |
query | map A standard MongoDB query. |
update | map A valid update document. Must use $set or $push , throws exception otherwise. |
:upsert? | optional boolean If no document is found, create a new one. Default is false . |
Returns
{:matched-count <number of matching documents>
:modified-count <number of modified documents>}
Examples
(update!)
Update matching documents. | Parameter | Description | | --- | --- | | `collection` | `keyword/string` The collection. | | `query` | `map` A standard MongoDB query. | | `update` | `map` A valid update document. Must use `$set` or `$push`, throws exception otherwise. | | `:upsert?` | `optional boolean` If no document is found, create a new one. Default is `false`. | **Returns** ```Clojure {:matched-count <number of matching documents> :modified-count <number of modified documents>} ``` **Examples** ```Clojure (update!) ```
(update-one! <collection> <query> <update> & :upsert? <boolean>)
Update first matching document.
Parameter | Description |
---|---|
collection | keyword/string The collection. |
query | map A standard MongoDB query. |
update | map A valid update document. Must use $set or $push , throws exception otherwise. |
:upsert? | optional boolean If no document is found, create a new one. Default is false . |
Returns
{:matched-count <0 or 1>
:modified-count <0 or 1>}
Examples
(update-one!)
Update first matching document. | Parameter | Description | | --- | --- | | `collection` | `keyword/string` The collection. | | `query` | `map` A standard MongoDB query. | | `update` | `map` A valid update document. Must use `$set` or `$push`, throws exception otherwise. | | `:upsert?` | `optional boolean` If no document is found, create a new one. Default is `false`. | **Returns** ```Clojure {:matched-count <0 or 1> :modified-count <0 or 1>} ``` **Examples** ```Clojure (update-one!) ```
(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))
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** ```Clojure (with-database "my-database-2" (insert! :users {:name "My Name"}) (fetch! :users)) ```
(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 | 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))
Functionally set up or change mongodb connection. Reverts to earlier settings when leaving scope. | Parameter | Description | | --- | --- | | `uri` | `string` Connection string. See the [API documentation](http://mongodb.github.io/mongo-java-driver/4.5/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html) for more details. | | `connection` | A connection object. | | `body` | Encapsulated program utilizing the connection. | **Returns** The result of the last encapsulated expression. **Examples** ```Clojure (with-mongo "mongodb://localhost:27017/my-database" (insert! :users {:name "My Name"}) (fetch! :users)) ```
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close