CRUD Operations

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:

document = { name: "Harriet", age: 36 }

If you're using Ruby version 2.2 or greater, you can optionally enclose your keys in quotes.

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:

collection.update_one({ name: "Harriet" }, { "$set": { age: 42 } })

If you're using an earlier version of Ruby, use the hashrocket symbol:

collection.update_one({ name: "Harriet" }, { "$set" => { age: 42 } })

Quoted strings and hashrockets for key-value pairs will work with any version of 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 write concern is 1 or higher.

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.

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

{ "_id" : 1, "item" : "26 inch monitor", "price" : NumberDecimal("428.79") }

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

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.

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

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)

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

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

client[:artists].find({}, session: session).explain
client[:artists].find({}, read: {mode: :secondary_preferred}).explain

client[:artists, read: {mode: :secondary_preferred}].find.explain

client[:artists].find.projection(:name => 1)

client[:artists].find.read(:mode => :secondary_preferred)

client[:artists].find.sort(:name => -1)

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find(:name => 'Flying Lotus').count_documents

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].estimated_document_count

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find(:name => 'Flying Lotus').count

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
client[:artists].find.distinct(:name )

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

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

client.database.command(dbStats: 1, readConcern: {level: :majority})

# 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( { dbStats: 1 }, read: { mode: secondary,
                                                     tag_sets: [ { 'dc' => 'nyc' } ] } )

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
artists = client[:artists]
artists.with(:read => { :mode => :primary_preferred }).find.to_a

client = Mongo::Client.new(
  [ '127.0.0.1:27017' ],
  read: { mode: :secondary, hedge: { enabled: true } },
)

Updating

Updating documents is possible by executing a single or multiple update, or by using the $findAndModify command.

update_one

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

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

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

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

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

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.

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.

Deleting

delete_one

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

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.

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.

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 GridFS page.

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:

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:

# 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:

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.

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:

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
# => #<Mongo::WriteConcern::Acknowledged:0x47289650367880 options={:w=>2}>

Although CRUD operations accept an options hash, they currently do not recognize the :write_concern option:

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:

# Uses w: 1
collection.with(write_concern: {w: 1}).insert_one(name: 'SUN Project')

Write concern can also be manually specified in Database#command:

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.

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:

class Symbol
  def bson_type
    BSON::String::BSON_TYPE
  end
end