Mongodb v0.4.3 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 default DBConnection.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} with DBConnection.LogEntry.t prepended to args or nil. See DBConnection.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 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

collection()
conn()
conn :: DbConnection.Conn
cursor()
result(t)
result(t) :: :ok | {:ok, t} | {:error, Mongo.Error.t}
result!(t)
result!(t) :: nil | t | no_return

Functions

aggregate(topology_pid, coll, pipeline, opts \\ [])

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)
child_spec(opts, child_opts \\ [])

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.

count(topology_pid, coll, filter, opts \\ [])

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!(topology_pid, coll, filter, opts \\ [])

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.

distinct(topology_pid, coll, field, filter, opts \\ [])

Finds the distinct values for a specified field across a collection.

Options

  • :max_time - Specifies a time limit in milliseconds
distinct!(topology_pid, coll, field, filter, opts \\ [])

Similar to distinct/5 but unwraps the result and raises on error.

find(topology_pid, coll, filter, opts \\ [])

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, coll, filter, opts \\ [])

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(topology_pid, coll, filter, opts \\ [])

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(topology_pid, coll, filter, replacement, opts \\ [])

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(topology_pid, coll, filter, update, opts \\ [])

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

Examples

Mongo.insert_many(pid, "users", [%{first_name: "John", last_name: "Smith"}, %{first_name: "Jane", last_name: "Doe"}])

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.

Examples

Mongo.insert_one(pid, "users", %{first_name: "John", last_name: "Smith"})

Similar to insert_one/4 but unwraps the result and raises on error.

object_id()
object_id :: BSON.ObjectId.t

Generates a new BSON.ObjectId.

replace_one(topology_pid, coll, filter, replacement, opts \\ [])

Replace a single document matching the filter with the new document.

Options

  • :upsert - if set to true creates a new document when no document matches the filter (default: false)
replace_one!(topology_pid, coll, filter, replacement, opts \\ [])

Similar to replace_one/5 but unwraps the result and raises on error.

start_link(opts)
start_link(Keyword.t) ::
  {:ok, pid} |
  {:error, Mongo.Error.t | term}

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, see DBConnection for pool dependent options, this option must be included with all requests contacting the pool if not DBConnection.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 using run/3, either a 1-arity fun, {module, function, args} with DBConnection.t prepended to args or nil (default: nil)
  • :ssl - Set to true 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 to true 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 to true 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.