Delete Documents

Overview

In this guide, you can learn how to use the Ruby driver to remove documents from a MongoDB collection by performing delete operations.

A delete operation removes one or more documents from a MongoDB collection. You can perform a delete operation by using the delete_one or delete_many methods.

Sample Data

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your Ruby application, create a Mongo::Client object that connects to an Atlas cluster and assign the following values to your database and collection variables:

database = client.use('sample_restaurants')
collection = database[:restaurants]

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Delete Operations

You can perform delete operations in MongoDB by using the following methods:

delete_one, which deletes the first document that matches the search criteria
delete_many, which deletes all documents that match the search criteria

Each delete method requires a query filter parameter, which specifies the search criteria that determine which documents to select for removal. To learn more about query filters, see the Specify a Query guide.

Delete One Document

The following example uses the delete_one method to remove a document in which the value of the name field is "Happy Garden":

filter = { name: 'Happy Garden' }
result = collection.delete_one(filter)
puts "Deleted #{result.deleted_count} document(s)"

Deleted 1 document(s)

Delete Multiple Documents

The following example uses the delete_many method to remove all documents in which the value of the borough field is "Brooklyn" and the value of the name field is "Starbucks":

filter = { name: 'Starbucks', borough: 'Brooklyn' }
result = collection.delete_many(filter)
puts "Deleted #{result.deleted_count} document(s)"

Deleted 3 document(s)

Customize the Delete Operation

You can pass a Hash object as a parameter to the delete_one and delete_many methods to set options to configure the delete operation. If you don't specify any options, the driver performs the delete operation with default settings.

The following table describes the options that you can use to configure the delete operation:

Option	Description
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`session`	Specifies the session to use for the operation. To learn more about sessions, see Client Sessions and Causal Consistency Guarantees in the MongoDB Server manual.
`hint`	Specifies the index to use when matching documents. For more information, see the hint option in the `delete` reference page of the MongoDB Server manual.
`let`	Provides a map of parameter names and values to set top-level variables for the operation. Values must be constant or closed expressions that don't reference document fields. For more information, see the let option in the `delete` reference page of the MongoDB Server manual.

Modify Delete Example

The following code specifies the hint option to instruct the delete operation to use the "name_index" index. Then, the example uses the delete_many method to delete all documents in the restaurants collection with a name field value that includes the string "Red".

filter = { name: /Red/ }
options = { hint: 'name_index' }
result = collection.delete_many(filter, options)
puts "Deleted #{result.deleted_count} document(s)"

Deleted 124 document(s)

Tip

If you use the the delete_one method in the preceding example instead of the delete_many method, the driver deletes only the first document that matches the query filter.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Update Documents

Bulk Write Operations