Mongodb v0.4.2 Mongo
The main entry point for doing queries. All functions take a topology to run the query on.
Generic options
All operations take these options.
:timeout
- The maximum time that the caller is allowed the to hold the connection’s state (ignored when using a run/transaction connection, default:15_000
):pool
- The pooling behaviour module to use, this option is required unless the defaultDBConnection.Connection
pool is used:pool_timeout
- The maximum time to wait for a reply when making a synchronous call to the pool (default:5_000
):queue
- Whether to block waiting in an internal queue for the connection’s state (boolean, default:true
):log
- A function to log information about a call, either a 1-arity fun,{module, function, args}
withDBConnection.LogEntry.t
prepended toargs
ornil
. SeeDBConnection.LogEntry
(default:nil
):database
- the database to run the operation on
Read options
All read operations that returns a cursor take the following options for controlling the behaviour of the cursor.
:batch_size
- Number of documents to fetch in each batch:limit
- Maximum number of documents to fetch with the cursor:read_preference
- specifies the rules for selecting a server to query
Write options
All write operations take the following options for controlling the write concern.
:w
- The number of servers to replicate to before returning from write operators, a 0 value will return immediately, :majority will wait until the operation propagates to a majority of members in the replica set (Default: 1):j
If true, the write operation will only return after it has been committed to journal - (Default: false):wtimeout
- If the write concern is not satisfied in the specified interval, the operation returns an error
Summary
Functions
Performs aggregation operation using the aggregation pipeline
Issue a database command. If the command has parameters use a keyword list for the document because the “command key” has to be the first in the document
Similar to command/3
but unwraps the result and raises on error
Returns the count of documents that would match a find/4
query
Similar to count/4
but unwraps the result and raises on error
Remove all documents matching the filter from the collection
Similar to delete_many/4
but unwraps the result and raises on error
Remove a document matching the filter from the collection
Similar to delete_one/4
but unwraps the result and raises on error
Finds the distinct values for a specified field across a collection
Similar to distinct/5
but unwraps the result and raises on error
Selects documents in a collection and returns a cursor for the selected documents
Selects a single document in a collection and returns either a document or nil
Finds a document and deletes it
Finds a document and replaces it
Finds a document and updates it (using atomic modifiers)
Insert multiple documents into the collection
Similar to insert_many/4
but unwraps the result and raises on error
Insert a single document into the collection
Similar to insert_one/4
but unwraps the result and raises on error
Generates a new BSON.ObjectId
Replace a single document matching the filter with the new document
Similar to replace_one/5
but unwraps the result and raises on error
Start and link to a database connection process
Update all documents matching the filter
Similar to update_many/5
but unwraps the result and raises on error
Update a single document matching the filter
Similar to update_one/5
but unwraps the result and raises on error
Types
Functions
aggregate(pid, collection, [BSON.document], Keyword.t) :: cursor
Performs aggregation operation using the aggregation pipeline.
Options
:allow_disk_use
- Enables writing to temporary files (Default: false):max_time
- Specifies a time limit in milliseconds:use_cursor
- Use a cursor for a batched response (Default: true)
command(pid, BSON.document, Keyword.t) :: result(<a href="BSON.html#t:document/0">BSON.document</a>)
Issue a database command. If the command has parameters use a keyword list for the document because the “command key” has to be the first in the document.
command!(pid, BSON.document, Keyword.t) :: result!(<a href="BSON.html#t:document/0">BSON.document</a>)
Similar to command/3
but unwraps the result and raises on error.
count(pid, collection, BSON.document, Keyword.t) :: result(non_neg_integer)
Returns the count of documents that would match a find/4
query.
Options
:limit
- Maximum number of documents to fetch with the cursor:skip
- Number of documents to skip before returning the first:hint
- Hint which index to use for the query
count!(pid, collection, BSON.document, Keyword.t) :: result!(non_neg_integer)
Similar to count/4
but unwraps the result and raises on error.
delete_many(pid, collection, BSON.document, Keyword.t) :: result(<a href="Mongo.DeleteResult.html#t:t/0">Mongo.DeleteResult.t</a>)
Remove all documents matching the filter from the collection.
delete_many!(pid, collection, BSON.document, Keyword.t) :: result!(<a href="Mongo.DeleteResult.html#t:t/0">Mongo.DeleteResult.t</a>)
Similar to delete_many/4
but unwraps the result and raises on error.
Remove a document matching the filter from the collection.
Similar to delete_one/4
but unwraps the result and raises on error.
distinct(pid, collection, String.t | atom, BSON.document, Keyword.t) :: result([<a href="BSON.html#t:t/0">BSON.t</a>])
Finds the distinct values for a specified field across a collection.
Options
:max_time
- Specifies a time limit in milliseconds
distinct!(pid, collection, String.t | atom, BSON.document, Keyword.t) :: result!([<a href="BSON.html#t:t/0">BSON.t</a>])
Similar to distinct/5
but unwraps the result and raises on error.
find(pid, collection, BSON.document, Keyword.t) :: cursor
Selects documents in a collection and returns a cursor for the selected documents.
Options
:comment
- Associates a comment to a query:cursor_type
- Set to :tailable or :tailable_await to return a tailable cursor:max_time
- Specifies a time limit in milliseconds:modifiers
- Meta-operators modifying the output or behavior of a query, see http://docs.mongodb.org/manual/reference/operator/query-modifier/:cursor_timeout
- Set to false if cursor should not close after 10 minutes (Default: true):sort
- Sorts the results of a query in ascending or descending order:projection
- Limits the fields to return for all matching document:skip
- The number of documents to skip before returning (Default: 0)
find_one(conn, collection, BSON.document, Keyword.t) :: cursor
Selects a single document in a collection and returns either a document or nil.
If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk.
Options
:comment
- Associates a comment to a query:cursor_type
- Set to :tailable or :tailable_await to return a tailable cursor:max_time
- Specifies a time limit in milliseconds:modifiers
- Meta-operators modifying the output or behavior of a query, see http://docs.mongodb.org/manual/reference/operator/query-modifier/:cursor_timeout
- Set to false if cursor should not close after 10 minutes (Default: true):projection
- Limits the fields to return for all matching document:skip
- The number of documents to skip before returning (Default: 0)
find_one_and_delete(pid, collection, BSON.document, Keyword.t) :: result(<a href="BSON.html#t:document/0">BSON.document</a>)
Finds a document and deletes it.
Options
:max_time
- The maximum amount of time to allow the query to run (in MS):projection
- Limits the fields to return for all matching documents.:sort
- Determines which document the operation modifies if the query selects multiple documents.:collation
- Optionally specifies a collation to use in MongoDB 3.4 and higher.
find_one_and_replace(pid, collection, BSON.document, BSON.document, Keyword.t) :: result(<a href="BSON.html#t:document/0">BSON.document</a>)
Finds a document and replaces it.
Options
:bypass_document_validation
- Allows the write to opt-out of document level validation:max_time
- The maximum amount of time to allow the query to run (in MS):projection
- Limits the fields to return for all matching documents.:return_document
- Returns the replaced or inserted document rather than the original. Values are :before or :after. (default is :before):sort
- Determines which document the operation modifies if the query selects multiple documents.:upsert
- Create a document if no document matches the query or updates the document.:collation
- Optionally specifies a collation to use in MongoDB 3.4 and higher.
find_one_and_update(pid, collection, BSON.document, BSON.document, Keyword.t) :: result(<a href="BSON.html#t:document/0">BSON.document</a>)
Finds a document and updates it (using atomic modifiers).
Options
:bypass_document_validation
- Allows the write to opt-out of document level validation:max_time
- The maximum amount of time to allow the query to run (in MS):projection
- Limits the fields to return for all matching documents.:return_document
- Returns the replaced or inserted document rather than the original. Values are :before or :after. (default is :before):sort
- Determines which document the operation modifies if the query selects multiple documents.:upsert
- Create a document if no document matches the query or updates the document.
insert_many(pid, collection, [BSON.document], Keyword.t) :: result(<a href="Mongo.InsertManyResult.html#t:t/0">Mongo.InsertManyResult.t</a>)
Insert multiple documents into the collection.
If any of the documents is missing the _id
field or it is nil
, an ObjectId
will be generated, and insertd into the document.
Ids of all documents will be returned in the result struct.
Options
:continue_on_error
- even if insert fails for one of the documents continue inserting the remaining ones (default:false
)
insert_many!(pid, collection, [BSON.document], Keyword.t) :: result!(<a href="Mongo.InsertManyResult.html#t:t/0">Mongo.InsertManyResult.t</a>)
Similar to insert_many/4
but unwraps the result and raises on error.
Insert a single document into the collection.
If the document is missing the _id
field or it is nil
, an ObjectId
will be generated, inserted into the document, and returned in the result struct.
Similar to insert_one/4
but unwraps the result and raises on error.
Generates a new BSON.ObjectId
.
Replace a single document matching the filter with the new document.
Options
:upsert
- if set totrue
creates a new document when no document matches the filter (default:false
)
Similar to replace_one/5
but unwraps the result and raises on error.
Start and link to a database connection process.
Options
:hostname
- Server hostname:port
- Server port:database
- Database:username
- Username:password
- User password:auth
- Additionally users to authenticate (list of keyword lists with the keys:username
and:password
):auth_source
- Database to authenticate against:pool
- The pool module to use, seeDBConnection
for pool dependent options, this option must be included with all requests contacting the pool if notDBConnection.Connection
(default:DBConnection.Connection
):idle
- The idle strategy,:passive
to avoid checkin when idle and:active
to checkin when idle (default::passive
):idle_timeout
- The idle timeout to ping the database (default:1_000
):backoff_min
- The minimum backoff interval (default:1_000
):backoff_max
- The maximum backoff interval (default:30_000
):backoff_type
- The backoff strategy,:stop
for no backoff and to stop,:exp
for exponential,:rand
for random and:rand_exp
for random exponential (default::rand_exp
):after_connect
- A function to run on connect usingrun/3
, either a 1-arity fun,{module, function, args}
withDBConnection.t
prepended toargs
ornil
(default:nil
):ssl
- Set totrue
if ssl should be used (default:false
):ssl_opts
- A list of ssl options, see the ssl docs
Update all documents matching the filter.
Uses MongoDB update operators to specify the updates. For more information please refer to the MongoDB documentation
Options
:upsert
- if set totrue
creates a new document when no document matches the filter (default:false
)
Similar to update_many/5
but unwraps the result and raises on error.
Update a single document matching the filter.
Uses MongoDB update operators to specify the updates. For more information please refer to the MongoDB documentation
Example:
Mongo.update_one(MongoPool,
"my_test_collection",
%{"filter_field": "filter_value"},
%{"$set": %{"modified_field": "new_value"}})
Options
:upsert
- if set totrue
creates a new document when no document matches the filter (default:false
)
Similar to update_one/5
but unwraps the result and raises on error.