Mongodb

v0.4.5

Mongodb v0.4.5 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 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

Link to this section Summary

Types

collection()
conn()
cursor()
result(t)
result!(t)

Functions

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

Performs aggregation operation using the aggregation pipeline

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

command!(topology_pid, query, opts \\ [])

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

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

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

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

Remove all documents matching the filter from the collection

delete_many!(topology_pid, coll, filter, opts \\ [])

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

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

Remove a document matching the filter from the collection

delete_one!(topology_pid, coll, filter, opts \\ [])

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

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

find_one(conn, coll, filter, opts \\ [])

Selects a single document in a collection and returns either a document or nil

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

Finds a document and deletes it

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

Finds a document and replaces it

find_one_and_update(topology_pid, coll, filter, update, opts \\ [])

Finds a document and updates it (using atomic modifiers)

insert_many(topology_pid, coll, docs, opts \\ [])

Insert multiple documents into the collection

insert_many!(topology_pid, coll, docs, opts \\ [])

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

insert_one(topology_pid, coll, doc, opts \\ [])

Insert a single document into the collection

insert_one!(topology_pid, coll, doc, opts \\ [])

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

object_id()

Generates a new BSON.ObjectId

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

Replace a single document matching the filter with the new document

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 and link to a database connection process

update_many(topology_pid, coll, filter, update, opts \\ [])

Update all documents matching the filter

update_many!(topology_pid, coll, filter, update, opts \\ [])

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

update_one(topology_pid, coll, filter, update, opts \\ [])

Update a single document matching the filter

update_one!(topology_pid, coll, filter, update, opts \\ [])

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

Link to this section Types

Link to this type collection() View Source 
collection() :: String.t()
Link to this type conn() View Source 
conn() :: DbConnection.Conn
Link to this type result(t) View Source 
result(t) :: :ok | {:ok, t} | {:error, Mongo.Error.t()}
Link to this type result!(t) View Source 
result!(t) :: nil | t | no_return()

Link to this section Functions

Link to this function aggregate(topology_pid, coll, pipeline, opts \\ []) View Source 
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)
  • :max_time - Specifies a time limit in milliseconds
  • :use_cursor - Use a cursor for a batched response (Default: true)
Link to this function child_spec(opts, child_opts \\ []) View Source
Link to this function command(topology_pid, query, opts \\ []) View Source 
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.

Link to this function command!(topology_pid, query, opts \\ []) View Source 
command!(GenServer.server(), BSON.document(), Keyword.t()) :: result!(BSON.document())

Similar to command/3 but unwraps the result and raises on error.

Link to this function count(topology_pid, coll, filter, opts \\ []) View Source 
count(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
  • :hint - Hint which index to use for the query
Link to this function count!(topology_pid, coll, filter, opts \\ []) View Source 
count!(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result!(non_neg_integer())

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

Link to this function delete_many(topology_pid, coll, filter, opts \\ []) View Source 
delete_many(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result(Mongo.DeleteResult.t())

Remove all documents matching the filter from the collection.

Link to this function delete_many!(topology_pid, coll, filter, opts \\ []) View Source 
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.

Link to this function delete_one(topology_pid, coll, filter, opts \\ []) View Source 
delete_one(GenServer.server(), collection(), BSON.document(), Keyword.t()) :: result(Mongo.DeleteResult.t())

Remove a document matching the filter from the collection.

Link to this function delete_one!(topology_pid, coll, filter, opts \\ []) View Source 
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.

Link to this function distinct(topology_pid, coll, field, filter, opts \\ []) View Source 
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
Link to this function distinct!(topology_pid, coll, field, filter, opts \\ []) View Source 
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.

Link to this function find(topology_pid, coll, filter, opts \\ []) View Source 
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)
Link to this function find_one(conn, coll, filter, opts \\ []) View Source 
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)
Link to this function find_one_and_delete(topology_pid, coll, filter, opts \\ []) View Source 
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.
Link to this function find_one_and_replace(topology_pid, coll, filter, replacement, opts \\ []) View Source 
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.
Link to this function find_one_and_update(topology_pid, coll, filter, update, opts \\ []) View Source 
find_one_and_update(GenServer.server(), collection(), BSON.document(), BSON.document(), Keyword.t()) :: result(BSON.document())

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.
Link to this function insert_many(topology_pid, coll, docs, opts \\ []) View Source 
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)

Examples 

Mongo.insert_many(pid, "users", [%{first_name: "John", last_name: "Smith"}, %{first_name: "Jane", last_name: "Doe"}])
Link to this function insert_many!(topology_pid, coll, docs, opts \\ []) View Source 
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.

Link to this function insert_one(topology_pid, coll, doc, opts \\ []) View Source 
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"})
Link to this function insert_one!(topology_pid, coll, doc, opts \\ []) View Source 
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.

Link to this function object_id() View Source 
object_id() :: BSON.ObjectId.t()

Generates a new BSON.ObjectId.

Link to this function replace_one(topology_pid, coll, filter, replacement, opts \\ []) View Source 
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 to true creates a new document when no document matches the filter (default: false)
Link to this function replace_one!(topology_pid, coll, filter, replacement, opts \\ []) View Source 
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.

Link to this function start_link(opts) View Source 
start_link(Keyword.t()) ::
  {:ok, pid()} |
  {:error, Mongo.Error.t() | term()}

Start and link to a database connection process.

Options

  • :url - A mongo connection url, options defined separately are used as default values
  • :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
Link to this function update_many(topology_pid, coll, filter, update, opts \\ []) View Source 
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 to true creates a new document when no document matches the filter (default: false)
Link to this function update_many!(topology_pid, coll, filter, update, opts \\ []) View Source 
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.

Link to this function update_one(topology_pid, coll, filter, update, opts \\ []) View Source 
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 to true creates a new document when no document matches the filter (default: false)
Link to this function update_one!(topology_pid, coll, filter, update, opts \\ []) View Source 
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.