Liking cljdoc? Tell your friends :D

com.timezynk.mongo

A functional Clojure wrapper for the modern Java MongoDB API.

A functional Clojure wrapper for the modern Java MongoDB API.
raw docstring

aggregateclj

(aggregate <collection> & <pipeline>)

MongoDB aggregation.

ParameterDescription
collectionkeyword/string Collection name.
pipelineThe 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}})
```
raw docstring

close-connection!clj

(close-connection! conn)

collationclj

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

ParameterDescription
localestring The two-letter ICU locale string.
:alternateoptional 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-firstoptional 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-variableoptional 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.
:strengthoptional 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)
```
raw docstring

collection-infoclj

(collection-info coll)

List full info of collection.

ParameterDescription
namekeyword/string Collection name.
List full info of collection.

| Parameter | Description |
| ---       | --- |
| `name`    | `keyword/string` Collection name. |
raw docstring

create-collection!clj

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

Create collection.

ParameterDescription
namekeyword/string Collection name.
:collationoptional collation object The collation of the collection.
:schemaoptional map The schema validation map.
:validationoptional map Validation logic outside of the schema.
:leveloptional 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}}]})
```
raw docstring

create-connection!clj

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

Create a connection object.

ParameterDescription
uristring Database location.
:retry-writes?optional boolean Sets whether writes should be retried if they fail due to a network error. Default is false.
:write-concernoptional 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)
```
raw docstring

create-index!clj

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

Create an index for a collection.

ParameterDescription
collectionkeyword/string Collection name.
keysmap/list(keyword/string) A document or a list of keywords or strings.
:background?optional boolean Create the index in the background. Default false.
:nameoptional string A custom name for the index.
:partial-filter-expressionoptional 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!)
```
raw docstring

delete!clj

(delete! <collection> <query>)

Delete matching documents.

ParameterDescription
collectionkeyword/string The collection.
querymap 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>}
```
raw docstring

delete-one!clj

(delete-one! <collection> <query>)

Delete first matching document.

ParameterDescription
collectionkeyword/string The collection.
querymap 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>}
```
raw docstring

drop-collection!clj

(drop-collection! coll)

drop-index!clj

(drop-index! coll index)

fetchclj

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

Fetch documents from collection.

ParameterDescription
collectionkeyword/string The collection.
querymap A standard MongoDB query.
:collationoptional collation object Collation used.
:limitoptional int Number of documents to fetch.
:onlyoptional map A MongoDB map of fields to include or exclude.
:skipoptional int Number of documents to skip before fetching.
:sortoptional 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)
```
raw docstring

fetch-and-delete-one!clj

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

fetch-and-replace-one!clj

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

fetch-and-update-one!clj

(fetch-and-update-one! <collection>
                       <query>
                       &
                       :return-new? <boolean>
                       :upsert? <boolean>)

Update first matching document.

ParameterDescription
collectionkeyword/string The collection.
querymap 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.
raw docstring

fetch-countclj

(fetch-count <collection>)
(fetch-count <collection> <query>)

Count the number of documents returned.

ParameterDescription
collectionkeyword/string The collection.
querymap 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.
raw docstring

fetch-oneclj

(fetch-one <collection>)
(fetch-one <collection> <query>)

Return only the first document retrieved.

ParameterDescription
collectionkeyword/string The collection.
querymap 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`.
raw docstring

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.

ParameterDescription
collectionkeyword/string The collection.
documentmap A document.
document-listlist(map) A list of documents.
:write-concernoptional 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"}])
```
raw docstring

list-collection-namesclj

(list-collection-names)

List keyworded names of all collections in database.

List keyworded names of all collections in database.
raw docstring

list-collectionsclj

(list-collections)

List full info of all collections in database.

List full info of all collections in database.
raw docstring

list-databasesclj

(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.
raw docstring

list-indexesclj

(list-indexes coll)

modify-collection!clj

(modify-collection! <name> & :name <string>)

Make updates to a collection.

ParameterDescription
namekeyword/string Collection name.
:nameoptional 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)
```
raw docstring

replace-one!clj

(replace-one! <collection> <query> <document> & :upsert? <boolean>)

Replace a single document.

ParameterDescription
collectionkeyword/string The collection.
querymap A standard MongoDB query.
documentmap 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>}
```
raw docstring

transactioncljmacro

(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))
```
raw docstring

update!clj

(update! <collection> <query> <update> & :upsert? <boolean>)

Update matching documents.

ParameterDescription
collectionkeyword/string The collection.
querymap A standard MongoDB query.
updatemap 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!)
```
raw docstring

update-one!clj

(update-one! <collection> <query> <update> & :upsert? <boolean>)

Update first matching document.

ParameterDescription
collectionkeyword/string The collection.
querymap A standard MongoDB query.
updatemap 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!)
```
raw docstring

with-databasecljmacro

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

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

ParameterDescription
databasestring Name of database to use.
bodyEncapsulated 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))
```
raw docstring

with-mongocljmacro

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

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

ParameterDescription
uristring Connection string. See the API documentation for more details.
connectionA connection object.
bodyEncapsulated 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))
```
raw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close