*************** CRUD Operations *************** .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none :depth: 1 :class: singlecol 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: .. code-block:: javascript document = { name: "Harriet", age: 36 } If you're using Ruby version 2.2 or greater, you can optionally enclose your keys in quotes. .. code-block:: javascript document = { "name": "Harriet", "age": 36 } 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: .. code-block:: ruby collection.update_one({ name: "Harriet" }, { "$set": { age: 42 } }) If you're using an earlier version of Ruby, use the hashrocket symbol: .. code-block:: ruby collection.update_one({ name: "Harriet" }, { "$set" => { age: 42 } }) Quoted strings and hashrockets for key-value pairs will work with any version of Ruby: .. code-block:: ruby collection.update_one({ "name" => "Harriet" }, { "$set" => { age: 42 } }) 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 :manual:`write concern` is 1 or higher. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') result = client[:artists].insert_one( { :name => 'FKA Twigs' } ) result.n # returns 1, because 1 document was inserted. result = client[:artists].insert_many([ { :name => 'Flying Lotus' }, { :name => 'Aphex Twin' } ]) result.inserted_count # returns 2, because 2 documents were inserted. .. _specify-decimal128: Specify a ``Decimal128`` number ------------------------------- .. versionadded:: 3.4 :manual:`Decimal128` is a :doc:`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 :manual:`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``: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test') price = BSON::Decimal128.new("428.79") client[:inventory].insert_one({ "_id" => 1, "item" => "26 inch monitor", "price" => price }) The above operation produces the following document: .. code-block:: javascript { "_id" : 1, "item" : "26 inch monitor", "price" : NumberDecimal("428.79") } You can also create a ``Decimal128`` object from a Ruby ``BigDecimal`` object, or with ``Decimal128.from_string()``. .. code-block:: ruby big_decimal = BigDecimal.new(428.79, 5) price = BSON::Decimal128.new(big_decimal) # => BSON::Decimal128('428.79') price = BSON::Decimal128.from_string("428.79") # => BSON::Decimal128('428.79') Query Cache =========== The Ruby driver provides a query cache. When enabled, the query cache will save the results of find and aggregation queries and return those saved results when the same queries are performed again. To read more about the query cache, visit the :ref:`query cache tutorial `. 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: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].find(:name => 'Flying Lotus').each do |document| #=> Yields a BSON::Document. end To query nested documents, specify the keys in nested order using dot notation. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].find("records.releaseYear": 2008).each do |document| #=> Yields a BSON::Document. end Legacy ``$query`` Syntax ------------------------ *This usage is deprecated.* The ``find`` method allows providing the query and the options using the legacy ``$query`` syntax in the first parameter: .. code-block:: ruby collection.find(:'$query' => {name: 'Mr. Smith'}) # Equivalent to: collection.find(name: 'Mr. Smith') collection.find(:'$query' => {name: 'Mr. Smith'}, :'$sort' => {age: 1}) # Equivalent to: collection.find(name: 'Mr. Smith').sort(age: 1) When the query is executed against MongoDB 3.2 or newer, the driver will use the protocol appropriate for the server version in question, automatically converting the query as needed to either a find command or an OP_MSG payload. .. _query-options: 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. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') documents = client[:artists].find(:name => 'Flying Lotus').skip(10).limit(10) documents.each do |document| #=> Yields a BSON::Document. end The following is a full list of the available options that can be added when querying and their corresponding methods as examples. .. list-table:: :header-rows: 1 :widths: 40 80 * - Option - Description * - ``allow_disk_use`` - When set to true, the server can write temporary data to disk while executing the find operation. This option is only available on MongoDB server versions 4.4 and newer. * - ``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. * - ``explain(**opts)`` - Returns the query plan for the query. Pass the :manual:`explain options ` via the keyword arguments using symbol keys. .. code-block:: ruby # All server versions - default explain behavior client[:artists].find.explain # MongoDB 3.0 and newer client[:artists].find.explain(verbosity: :query_planner) client[:artists].find.explain(verbosity: :execution_stats) client[:artists].find.explain(verbosity: :all_plans_execution) # Alternative syntax using camel case client[:artists].find.explain(verbosity: "queryPlanner") client[:artists].find.explain(verbosity: "executionStats") client[:artists].find.explain(verbosity: "allPlansExecution") # MongoDB 2.6 client[:artists].find.explain(verbose: true) The explain operation supports ``:session`` and ``:read`` (for read preference) options. To specify these options for a single explain operation, they must be given to the ``find`` method as follows: .. code-block:: ruby client[:artists].find({}, session: session).explain client[:artists].find({}, read: {mode: :secondary_preferred}).explain If the read preference option is specified on the client or on the collection, it will be passed to the explain operation: .. code-block:: ruby client[:artists, read: {mode: :secondary_preferred}].find.explain Note that the session option is not accepted when creating a collection object. The explain command does not support passing the read concern option. If the read concern is specifed on the client or collection level, or if the read concern is specified as a find option, it will NOT be passed by the driver to the explain command. .. note:: The information returned by the server for the ``explain`` command varies with server version and deployment topology. The driver's ``explain`` method returns whatever the server provided. **The return value of ``explain`` method is not part of the driver's public API and depends on the server version and deployment topology.** * - ``hint(Hash)`` - Provides the query with an :manual:`index hint` to use. * - ``let(Hash)`` - Mapping of :manual:`variables` to use in the query. * - ``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. * - ``max_time_ms(Integer)`` - The maximum amount of time to allow the query to run, in milliseconds. * - ``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. .. code-block:: ruby client[:artists].find.projection(:name => 1) * - ``read(Hash)`` - Changes the read preference for this query only. .. code-block:: ruby client[:artists].find.read(:mode => :secondary_preferred) * - ``session(Session)`` - The session to use. * - ``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. .. code-block:: ruby client[:artists].find.sort(:name => -1) Additional Query Operations --------------------------- ``count_documents`` Get the total number of documents matching a filter, or the total number of documents in a collection. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].find(:name => 'Flying Lotus').count_documents ``estimated_document_count`` Get an approximate number of documents in the collection. Note that unlike ``count_documents``, ``estimated_document_count`` does not accept a filter. The ``count`` server command is used to implement ``estimated_document_count``. More information can be found via `Count: Behavior `_. Due to an oversight in MongoDB versions 5.0.0-5.0.7, the ``count`` command, which ``estimated_document_count`` uses in its implementation, was not included in v1 of the Stable API. Therefore, users of the Stable API with ``estimated_document_count`` are recommended to upgrade their server version to 5.0.8+ or set ``api_strict: false`` to avoid encountering errors. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].estimated_document_count ``count`` Get an approximate number of documents matching a filter, or an approximate number of documents in the collection. *Deprecated:* The ``count`` method is deprecated and does not work in transactions. Please use ``count_documents`` to obtain an exact count of documents potentially matching a filter or ``estimated_document_count`` to obtain an approximate number of documents in the collection. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].find(:name => 'Flying Lotus').count ``distinct`` Filters out documents with duplicate values. Equivalent to the SQL ``distinct`` clause. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].find.distinct(:name ) Tailable Cursors ---------------- For capped collections you may use a :manual:`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: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') client[:artists].drop client[:artists, capped: true, size: 512].create result = client[:artists].insert_many([ { :name => 'Flying Lotus' }, { :name => 'Aphex Twin' } ]) enum = client[:artists].find({}, cursor_type: :tailable_await).to_enum while true doc = enum.next # do something sleep(1) end Read Concern ------------ Read concern can be :ref:`set on the client ` or on the collection: .. code-block:: ruby client = Mongo::Client.new(['localhost:14420'], database: 'music', read_concern: {level: :local}) client['collection'].find.to_a collection = client['collection', read_concern: {level: :majority}] collection.find.to_a The driver does not currently support setting read concern on an individual query. Read concern can be specified when :ref:`starting a transaction `. When a transaction is active, :manual:`any read concern specified on the client or on the collection is ignored `. When using the generic command helper, the read concern can be specified as part of the command: .. code-block:: ruby client.database.command(collstats: 'test', readConcern: {level: :majority}) .. _read-preference: Read Preference --------------- Read preference determines the candidate :manual:`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**, the ``hedge`` option, which is a Hash specifying hedged read behavior, 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: .. code-block:: ruby # Set read preference on a client, used for all operations client = Mongo::Client.new([ '127.0.0.1:27017' ], read: { mode: :secondary, tag_sets: [ { 'dc' => 'nyc' } ] } ) # Set read preference for a given command client.database.command( { collstats: 'test' }, read: { mode: secondary, tag_sets: [ { 'dc' => 'nyc' } ] } ) Read preference can also be set for specific operations on a collection using the ``with`` method: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] artists.with(:read => { :mode => :primary_preferred }).find.to_a Mode ---- There are five possible read preference modes: ``:primary``, ``:secondary``, ``:primary_preferred``, ``:secondary_preferred`` and``:nearest``. Please see the :manual:`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 :manual:`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. Hedge ----- The ``hedge`` parameter is a Hash that specifies whether the server should use hedged reads. With hedged reads, sharded clusters can route read operations to two replica set members and return results from the first respondent. The ``hedge`` option may only be specified on non-primary read preferences. It must be provided as Hash with the key ``enabled`` set to ``true`` or ``false``. .. code-block:: ruby client = Mongo::Client.new( [ '127.0.0.1:27017' ], read: { mode: :secondary, hedge: { enabled: true } }, ) See the :manual:`MongoDB Manual ` for more information about hedged reads. .. note:: The ``hedge`` option is only available on MongoDB server versions 4.4 and newer. Attempting to use this option on older server versions will result in an error. .. _updating: Updating ======== Updating documents is possible by executing a single or multiple update, or by using the ``$findAndModify`` command. ``update_one`` .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] result = artists.find(:name => 'Goldie').update_one("$inc" => { :plays => 1 } ) result.n # Returns 1. result = artists.update_one( { :name => 'Goldie' }, { "$inc" => { :plays => 1 } } ) result.n # Returns 1. ``update_many`` .. code-block:: ruby result = artists.find(:label => 'Hospital').update_many( "$inc" => { :plays => 1 } ) result.modified_count # Returns the number of documents that were updated. result = artists.update_many( { :label => 'Hospital' }, { "$inc" => { :plays => 1 } } ) result.modified_count # Returns the number of documents that were updated. ``replace_one`` .. code-block:: ruby result = artists.find(:name => 'Aphex Twin').replace_one(:name => 'Richard James') result.modified_count # Returns 1. result = artists.replace_one( { :name => 'Aphex Twin' }, { :name => 'Richard James' } ) result.modified_count # Returns 1. 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`` .. code-block:: ruby client = Mongo::Client.new( [ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] artists.find(:name => 'José James').find_one_and_delete # Returns the document. ``find_one_and_replace`` .. code-block:: ruby doc = artists.find(:name => 'José James').find_one_and_replace(:name => 'José') doc # Return the document before the update. doc = artists.find_one_and_replace({ :name => 'José James' }, { :name => 'José' }) doc # Return the document before the update. doc = artists.find(:name => 'José James'). find_one_and_replace( { :name => 'José' }, :return_document => :after ) doc # Return the document after the update. ``find_one_and_update`` .. code-block:: ruby doc = artists.find(:name => 'José James'). find_one_and_update( '$set' => { :name => 'José' } ) doc # Return the document before the update. doc = artists.find_one_and_update( { :name => 'José James' }, { '$set' => { :name => 'José' } } ) doc # Return the document before the update. Update Options -------------- To add options to an update command, specify them as key-value pairs in the options Hash argument. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] artists.indexes.create_one(name: 1) # Force the server to use the name index to perform this operation result = artists.update_one( { :name => 'Goldie' }, { "$inc" => { :plays => 1 } }, { hint: { name: 1 } } ) result.n # Returns 1. The following is a list of the options that can be added to update operations, including ``update_one``, ``update_many``, ``replace_one``, ``find_one_and_delete``, ``find_one_and_update``, and ``find_one_and_replace``. .. list-table:: :header-rows: 1 :widths: 40 80 * - Option - Description * - ``array_filters`` - An Array of filter documents that determine which array elements to modify for an update operation on an array field. * - ``bypass_document_validation`` - Whether to skip document-level validation before writing the document. * - ``collation`` - Specifies a set of rules to use when comparing strings complying with the conventions of a particular language. * - ``hint`` - The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or as a String (e.g. "_id_"). Supported on MongoDB server versions 4.2 and newer for ``update_one``, ``update_many``, and ``replace_one`` commands, and on server versions 4.4 and newer for ``find_one_and_delete``, ``find_one_and_update``, and ``find_one_and_replace`` commands. * - ``let(Hash)`` - Mapping of :manual:`variables` to use for this operation. * - ``projection`` - The fields to exclude or include in the operation result (only available on ``find_one_and_delete``, ``find_one_and_replace``, and ``find_one_and_update`` commands). * - ``return_document`` - A symbol specifying whether to return the updated document as it was before or after the update. Potential values are ``:before`` or ``:after``. (Only available on ``find_one_and_update`` and ``find_one_and_replace`` commands). * - ``sort`` - How to sort the results of a find and modify command. Specified as a Hash key-value pair, where the key is the name of the field to sort by, and the value is either 1 or -1, specifying a sort in ascending or descending order (only available on ``find_one_and_delete``, ``find_one_and_replace``, and ``find_one_and_update`` commands). * - ``session`` - The session to use for this operation. * - ``upsert`` - Whether to upsert if the document doesn't exist. Cannot be used on ``find_one_and_delete`` operation. For more information about update options, see the MongoDB server documentation on the following commands: - :manual:`update ` - :manual:`findAndModify ` Deleting ======== ``delete_one`` .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] result = artists.find(:name => 'Björk').delete_one result.deleted_count # Returns 1. result = artists.delete_one(:name => 'Björk') result.deleted_count # Returns 1. ``delete_many`` .. code-block:: ruby result = artists.find(:label => 'Mute').delete_many result.deleted_count # Returns the number deleted. result = artists.delete_many(:label => 'Mute') result.deleted_count # Returns the number deleted. Delete Options -------------- To add options to a delete command, specify them as key-value pairs in the options Hash argument. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] artists.indexes.create_one(name: 1) # Force the server to use the name index to perform this operation result = artists.find(:name => 'Björk').delete_one(hint: { name: 1 }) result.deleted_count # Returns 1. The following is a full list of the available options that can be added to ``delete_one`` and ``delete_many`` operations. .. list-table:: :header-rows: 1 :widths: 40 80 * - Option - Description * - ``collation`` - Specifies a set of rules to use when comparing strings complying with the conventions of a particular language. * - ``hint`` - The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or as a String (e.g. "_id_"). Supported on MongoDB server versions 4.4 and newer. * - ``let(Hash)`` - Mapping of :manual:`variables` to use for this operation. * - ``session`` - The session to use for this operation. For more information about update options, see the MongoDB server documentation on the :manual:`delete command. ` .. _write-concern: 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 collection 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 :ref:`GridFS ` page. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) alt_client = client.with(write_concern: {w: :majority}) collection = client[:artists, write_concern: {w: 3}] alt_collection = collection.with(write_concern: {w: :majority}) # Uses w: 3 collection.insert_one({name: 'SUN Project'}) # Uses w: :majority alt_collection.insert_one({name: 'SUN Project'}) 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: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write: {w: 2}) alt_client = client.with(write: {w: :majority}) collection = client[:artists, write: {w: 3}] alt_collection = collection.with(write: {w: :majority}) If both ``:write`` and ``:write_concern`` options are provided, their values must be identical or an exception will be raised: .. code-block:: ruby # OK client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 3}, write: {w: 3}) # Error client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 3}, write: {w: :majority}) When ``#with`` methods are used to alter the options on a client or collection, the last provided option wins in case of naming differences: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) alt_client = client.with(write: {w: 3}) alt_client.options[:write] # => {"w"=>3} alt_client.options[:write_concern] # => nil 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. .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) collection = client[:artists, write_concern: {w: :majority}] session = client.start_session session.with_transaction do collection.insert_one({test: 1}, session: session) # Uses w: 2 when committing end session = client.start_session(default_transaction_options: {write_concern: {w: 3}) ) session.with_transaction do collection.insert_one({test: 1}, session: session) # Uses w: 3 when committing end session = client.start_session session.with_transaction(write_concern: {w: 3}) do collection.insert_one({test: 1}, session: session) # Uses w: 3 when committing end 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: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 1, j: true}) collection = client[:artists, write_concern: {w: 2}] collection.write_concern.options # => #2}> Although CRUD operations accept an options hash, they currently do not recognize the ``:write_concern`` option: .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) collection = client[:artists, write_concern: {w: :majority}] # Still uses w: :majority collection.insert_one({name: 'SUN Project'}, write_concern: {w: 1}) The easiest workaround for this is to use ``#with`` to obtain a new collection instance with the desired write concern: .. code-block:: ruby # Uses w: 1 collection.with(write_concern: {w: 1}).insert_one(name: 'SUN Project') Write concern can also be manually specified in ``Database#command``: .. code-block:: ruby client.database.command(create: 'foo-collection', writeConcern: {w: :majority}) 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. .. _dots-dollars-in-field-names: Field Names with Dots/Periods (.) and Dollar Signs ($) ====================================================== Starting in Mongo Ruby Driver version 2.18.0, the ability to work with fields that begin with dollar signs ($) and fields with dots/periods (.) in them is available. In Driver version 2.17.0 and earlier, any attempt to work with dotted or dollared fields would result in an ``IllegalKey`` error being raised. See the MongoDB docs on `Field Names with Periods (.) and Dollar Signs ($) `_ for more information on working with these types of fields. 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. To override default behavior and configure the driver to encode symbol values as strings, include the following code snippet in your project: .. code-block:: ruby class Symbol def bson_type BSON::String::BSON_TYPE end end