CRUD Operations¶
On this page
CRUD operations are those which deal with creating, reading, updating, and deleting documents.
Key-value Pair Notation¶
Key-value pairs appear in many different contexts in the MongoDB Ruby driver, and there are some quirks of syntax with regard to how they can be notated which depend on which version of Ruby you’re using.
When constructing a document, the following syntax is acceptable and correct for Ruby version 1.9 and later:
If you’re using Ruby version 2.2 or greater, you can optionally enclose your keys in quotes.
If you need to use any MongoDB operator which begins with $
,
such as $set
, $gte
, or $near
, you must enclose it in
quotes. If you’re using Ruby version 2.2 or greater, you can notate
it as follows:
If you’re using an earlier version of Ruby, use the hashrocket symbol:
Quoted strings and hashrockets for key-value pairs will work with any version of Ruby:
Creating Documents¶
To insert documents into a collection, select a
collection on the client and call insert_one
or insert_many
.
Insert operations return a Mongo::Operation::Result
object which
gives you information about the insert itself.
On MongoDB 2.6 and later, if the insert fails, an exception is raised, because write commands are used.
On MongoDB 2.4, an exception is only raised if the insert fails and the write concern is 1 or higher.
Specify a Decimal128
number¶
New in version 3.4.
Decimal128 is a BSON datatype that employs 128-bit decimal-based floating-point values capable of emulating decimal rounding with exact precision. This functionality is intended for applications that handle monetary data, such as financial and tax computations.
The following example inserts a value of type Decimal128
into
the price
field of a collection named inventory
:
The above operation produces the following document:
You can also create a Decimal128
object from a Ruby BigDecimal
object, or with Decimal128.from_string()
.
Reading¶
The Ruby driver provides a fluent interface for queries using the find
method on the collection. Various options are available
to the find
method.
The query is lazily executed against the server only when iterating the
results - at that point the query is dispatched and a Mongo::Cursor
is
returned.
To find all documents for a given filter, call find
with the
query:
To query nested documents, specify the keys in nested order using dot notation.
Query Options¶
To add options to a query, chain the appropriate methods after the
find
method. Note that the underlying object, the Mongo::Collection::View
,
is immutable and a new object will be returned after each method call.
The following is a full list of the available options that can be added when querying and their corresponding methods as examples.
Option | Description |
---|---|
allow_partial_results |
For use with sharded clusters. If a shard is down, allows the query to return results from the shards that are up, potentially only getting a portion of the results. |
batch_size(Integer) |
Specifies the size of each batch of documents the cursor will return on
each GETMORE operation. |
comment(String) |
Adds a comment to the query. |
hint(Hash) |
Provides the query with an index hint to use. |
limit(Integer) |
Limits the number of returned documents to the provided value. |
max_scan(Integer) |
Sets the maximum number of documents to scan if a full collection scan would be performed. Deprecated as of MongoDB server version 4.0. |
no_cursor_timeout |
MongoDB automatically closes inactive cursors after a period of 10 minutes. Call this for cursors to remain open indefinitely on the server. |
projection(Hash) |
Specifies the fields to include or exclude from the results. |
read(Hash) |
Changes the read preference for this query only. |
show_disk_loc(Boolean) |
Tells the results to also include the location of the documents on disk. |
skip(Integer) |
Skip the provided number of documents in the results. |
snapshot |
Execute the query in snapshot mode. Deprecated as of MongoDB server version 4.0. |
sort(Hash) |
Specifies sort criteria for the query. |
Additional Query Operations¶
count
- Get the total number of documents an operation returns.
distinct
- Filters out documents with duplicate values. Equivalent to the SQL
distinct
clause.
Tailable Cursors¶
For capped collections you may use a tailable cursor that remains open after the client exhausts the results in the initial cursor. The following code example shows how a tailable cursor might be used:
Read Preference¶
Read preference determines the candidate replica set members to which a query or command can be sent. They consist of a mode specified as a symbol, an array of hashes known as tag_sets, and two timing options: local_threshold and server_selection_timeout.
local_threshold
- Defines the upper limit in seconds of the latency window between the nearest server and suitable servers to which an operation may be sent. The default is 15 milliseconds, or 0.015 seconds.
server_selection_timeout
- Defines how long to block for server selection before throwing an exception. The default is 30,000 milliseconds, or 30 seconds.
Note
Read preference does not apply to Standalone deployments. When a client is connected to a Standalone deployment, any application-specified read preference is ignored.
For more information on the algorithm used to select a server, please refer to the Server Selection documentation, available on GitHub.
Read preference can be set as an option on the client or passed an option when a command is run on a database:
Read preference can also be set for specific operations on a collection
using the with
method:
Mode¶
There are five possible read preference modes: :primary
, :secondary
,
:primary_preferred
, :secondary_preferred
and``:nearest``.
Please see the read preference documentation in the MongoDB Manual for an explanation of the modes.
Note
When a client is directly connected to a server using the :direct_connection
Ruby option or the directConnection
URI option, read preference mode
is automatically set to :primary_preferred
to permit read operations
against secondaries. If the application specified a :primary
read
preference mode, the mode is automatically converted to :primary_preferred
.
If another read preference mode is specified, it is passed to the server
unchanged.
Tag sets¶
The tag_sets
parameter is an ordered list of tag sets used to
restrict the eligibility of servers for selection, such as for data
center awareness. Please see the read preference documentation in
the MongoDB Manual for an explanation of tag sets.
A read preference tag set (T) matches a server tag set (S) – or equivalently a server tag set (S) matches a read preference tag set (T) — if T is a subset of S.
For example, the read preference tag set { dc: 'ny', rack: 2 }
matches a secondary server with tag set { dc: 'ny', rack: 2, size: 'large' }
.
A tag set that is an empty document matches any server, because
the empty tag set is a subset of any tag set. This means the default
tag_sets
parameter [{}]
matches all servers.
Updating¶
Updating documents is possible by executing a single or
multiple update, or by using the $findAndModify
command.
update_one
update_many
replace_one
To update documents and return a document via $findAndModify
, use one of
the three provided helpers: find_one_and_delete
, find_one_and_replace
,
or find_one_and_update
. You can opt to return the document before or after
the modification occurs.
find_one_and_delete
find_one_and_replace
find_one_and_update
find_one_and_replace
Write Concern¶
All write operations in MongoDB are executed with a write concern which is the level of acknowledgment requested from MongoDB for the particular write. More information about write concerns in general is available in the MongoDB manual.
The Ruby driver supports specifying write concern on client, collection,
session (for transactions on that session), transaction, GridFS bucket
and write stream levels, as well as when manually issuing commands via
Database#command
.
As of driver version 2.10, all driver objects accepting write concerns do so
through the :write_concern
option, which should be given a hash with
the write concern options. Usage of the :write
option is deprecated.
In driver versions 2.9 and below, client, collection and GridFS objects
took write concern options in the :write
option with session and
transaction objects employing the :write_concern
option.
Below are some examples of passing write concerns to client and colection
objects. The :write_concern
option can be provided when constructing
new client and collection objects, or to the #with
methods.
GridFS examples are provided on the GridFS page.
Driver versions 2.9 and earlier accepted write concerns on client and collection
level via the :write
option. This usage continues to be supported for
backwards compatibility, but is deprecated:
If both :write
and :write_concern
options are provided, their
values must be identical or an exception will be raised:
When #with
methods are used to alter the options on a client or collection,
the last provided option wins in case of naming differences:
When using transactions, write concern is only sent to the server in
commit_transaction
and abort_transaction
operations
per the transactions specification.
Write concern may be set via the :write_concern
option in a
with_transaction
or start_transaction
call, or via
default_transaction_options
option on a session object.
If neither of these is set, write concern of the client is used; note
that transactions ignore write concerns of collections that are involved
in their operations. Note that when setting the write concern as a
transaction option, the :write
option is not recognized by any
driver version.
When write concerns are inherited, inheritance applies to the entire
write concern hash rather than individual elements. For example, j: true
is not inherited in the following case:
Although CRUD operations accept an options hash, they currently do not
recognize the :write_concern
option:
The easiest workaround for this is to use #with
to obtain a new collection
instance with the desired write concern:
Write concern can also be manually specified in Database#command
:
Note that writeConcern here is part of the operation rather than options, and the syntax is the camel case one that MongoDB server recognizes, not the underscore one that Ruby driver uses.
A Note about the BSON Symbol type¶
Because the BSON specification deprecated the BSON symbol type, the bson gem will serialize Ruby symbols into BSON strings when used on its own. However, in order to maintain backwards compatibility with older datasets, the Ruby driver overrides this behavior to serialize Ruby symbols as BSON symbols. This is necessary to be able to specify queries for documents which contain BSON symbols as fields. Despite this, new documents with symbol type fields should not be stored in the database; instead, use string fields.