Mongodb v0.5.0 Mongo View Source
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:connect_timeout_ms
- maximum timeout for connect (default:5_000
)
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
Link to this section 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_documents/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
Estimate the number of documents in a collection using collection metadata
Similar to estimated_document_count/3
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
Convenient function that returns a cursor with the names of the indexes
Returns a cursor to enumerate all indexes
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
Getting Collection Names
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
Link to this section Types
initial_type() :: :unknown | :single | :replica_set_no_primary | :sharded
Link to this section Functions
aggregate(GenServer.server(), collection(), [BSON.document()], Keyword.t()) :: cursor()
Performs aggregation operation using the aggregation pipeline.
Options
:allow_disk_use
- Enables writing to temporary files (Default: false):collation
- Optionally specifies a collation to use in MongoDB 3.4 and:max_time
- Specifies a time limit in milliseconds:use_cursor
- Use a cursor for a batched response (Default: true)
command(GenServer.server(), BSON.document(), Keyword.t()) :: result(BSON.document())
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!(GenServer.server(), BSON.document(), Keyword.t()) :: result!(BSON.document())
Similar to command/3
but unwraps the result and raises on error.
count_documents(GenServer.server(), 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
count_documents!(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result!(non_neg_integer())
Similar to count_documents/4
but unwraps the result and raises on error.
delete_many(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result(Mongo.DeleteResult.t())
Remove all documents matching the filter from the collection.
delete_many!(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result!(Mongo.DeleteResult.t())
Similar to delete_many/4
but unwraps the result and raises on error.
delete_one(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result(Mongo.DeleteResult.t())
Remove a document matching the filter from the collection.
delete_one!(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result!(Mongo.DeleteResult.t())
Similar to delete_one/4
but unwraps the result and raises on error.
distinct(GenServer.server(), collection(), String.t() | atom(), BSON.document(), Keyword.t()) :: result([BSON.t()])
Finds the distinct values for a specified field across a collection.
Options
:max_time
- Specifies a time limit in milliseconds:collation
- Optionally specifies a collation to use in MongoDB 3.4 and
distinct!(GenServer.server(), collection(), String.t() | atom(), BSON.document(), Keyword.t()) :: result!([BSON.t()])
Similar to distinct/5
but unwraps the result and raises on error.
estimated_document_count(GenServer.server(), collection(), Keyword.t()) :: result(non_neg_integer())
Estimate the number of documents in a collection using collection metadata.
estimated_document_count!(GenServer.server(), collection(), Keyword.t()) :: result!(non_neg_integer())
Similar to estimated_document_count/3
but unwraps the result and raises on
error.
find(GenServer.server(), 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(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: BSON.document() | nil
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(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result(BSON.document())
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(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result(BSON.document())
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(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result(BSON.document()) | {:ok, nil}
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.:collation
- Optionally specifies a collation to use in MongoDB 3.4 and
insert_many(GenServer.server(), collection(), [BSON.document()], Keyword.t()) :: result(Mongo.InsertManyResult.t())
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
):ordered
- A boolean specifying whether the mongod instance should perform an ordered or unordered insert. (default:true
)
Examples
Mongo.insert_many(pid, "users", [%{first_name: "John", last_name: "Smith"}, %{first_name: "Jane", last_name: "Doe"}])
insert_many!(GenServer.server(), collection(), [BSON.document()], Keyword.t()) :: result!(Mongo.InsertManyResult.t())
Similar to insert_many/4
but unwraps the result and raises on error.
insert_one(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result(Mongo.InsertOneResult.t())
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.
Examples
Mongo.insert_one(pid, "users", %{first_name: "John", last_name: "Smith"})
insert_one!(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result!(Mongo.InsertOneResult.t())
Similar to insert_one/4
but unwraps the result and raises on error.
list_index_names(GenServer.server(), String.t(), Keyword.t()) :: %Stream{accs: term(), done: term(), enum: term(), funs: term()}
Convenient function that returns a cursor with the names of the indexes.
list_indexes(GenServer.server(), String.t(), Keyword.t()) :: cursor()
Returns a cursor to enumerate all indexes
Generates a new BSON.ObjectId
.
replace_one(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result(Mongo.UpdateResult.t())
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
)
replace_one!(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result!(Mongo.UpdateResult.t())
Similar to replace_one/5
but unwraps the result and raises on error.
show_collections(GenServer.server(), Keyword.t()) :: cursor()
Getting Collection Names
start_link(Keyword.t()) :: {:ok, pid()} | {:error, Mongo.Error.t() | atom()}
Start and link to a database connection process.
Options
:database
- The database to use (required):hostname
- The host to connect to (require):port
- The port to connect to your server (default: 27017):url
- A mongo connection url. Can be used in place of:hostname
and:database
(optional):seeds
- A list of host names in the cluster. Can be used in place of:hostname
(optional):username
- The User to connect with (optional):password
- The password to connect with (optional):auth
- List of additional users to authenticate as a keyword list with:username
and:password
keys (optional):auth_source
- The database to authenticate against:set_name
- The name of the replica set to connect to (required if connecting to a replica set):type
- a hint of the topology type. Seeinitial_type/0
for valid values (default::unknown
):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 checking when idle (default::passive
):idle_timeout
- The idle timeout to ping the database (default:1_000
):connect_timeout_ms
- The maximum timeout for the initial connection (default:5_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
of exponential,:rand
for random and:ran_exp
for random exponential (default::rand_exp
):after_connect
- A function to run on connect userun/3
. Either a 1-arity fun,{module, function, args}
withDBConnection.t
, prepended toargs
ornil
(default:nil
):auth_mechanism
- options for the mongo authentication mechanism, currently only supports:x509
atom as a value:ssl
- Set totrue
if ssl should be used (default:false
):ssl_opts
- A list of ssl options, see the ssl docs
Error Reasons
:single_topology_multiple_hosts
- A topology of:single
was set but multiple hosts were given:set_name_bad_topology
- A:set_name
was given but the topology was set to something other than:replica_set_no_primary
or:single
update_many(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result(Mongo.UpdateResult.t())
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
)
update_many!(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result!(Mongo.UpdateResult.t())
Similar to update_many/5
but unwraps the result and raises on error.
update_one(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result(Mongo.UpdateResult.t())
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
)
update_one!(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result!(Mongo.UpdateResult.t())
Similar to update_one/5
but unwraps the result and raises on error.