Retrieve Data

Sample Data

The examples in this guide use the companies collection in the sample_training 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_training')
collection = database[:companies]

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

Find Multiple Documents

To find multiple documents in a collection, pass a query filter to the find method that specifies the criteria of the documents you want to retrieve.

The following example uses the find method to find all documents in which the founded_year field has the value 1970:

results = collection.find(founded_year: 1970)

When you call the each method on the Mongo::Collection::View object representing the query, the driver returns a Mongo::Cursor object. A cursor is a mechanism that allows an application to iterate over database results while holding only a subset of them in memory at a given time. Cursors are useful when your find method returns a large amount of documents.

The following code calls the each method to iterate over the query results:

results.each do |doc|
  puts doc
end

{"_id"=>BSON::ObjectId('...'), "name"=>"Mitsubishi Motors", "permalink"=>"mitsubishi-motors",
"crunchbase_url"=>"http://www.crunchbase.com/company/mitsubishi-motors",
"homepage_url"=>"http://www.mitsubishi-motors.com", ...}
{"_id"=>BSON::ObjectId('...'), "name"=>"Western Digital", "permalink"=>"western-digital",
"crunchbase_url"=>"http://www.crunchbase.com/company/western-digital",
"homepage_url"=>"http://www.wdc.com/en", ...}
{"_id"=>BSON::ObjectId('...'), "name"=>"Celarayn", "permalink"=>"celarayn",
"crunchbase_url"=>"http://www.crunchbase.com/company/celarayn",
"homepage_url"=>"http://www.celarayn.es", ...}

results = collection.find

Find One Document

To find a single document in a collection, call the find method and pass a query filter that specifies the criteria of the document you want to find. Then, chain the first method to find.

If the query filter matches more than one document, the first method retrieves the first matching document from the operation results.

The following example chains the first method to find to find the first document in which the name field has the value 'LinkedIn':

document = collection.find(name: 'LinkedIn').first
puts document

{"_id"=>BSON::ObjectId('...'), "name"=>"LinkedIn", "permalink"=>"linkedin",
"crunchbase_url"=>"http://www.crunchbase.com/company/linkedin",
"homepage_url"=>"http://linkedin.com", "blog_url"=>"http://blog.linkedin.com",
...}

Modify Find Behavior

You can chain option methods to the find method to modify the operation results. The following table describes some of these options:

The following example uses the find method to find all documents in which the number_of_employees field has the value 1000. The example uses the limit option to return a maximum of 2 results:

limit_results = collection.find(number_of_employees: 1000).limit(2)
limit_results.each do |doc|
  puts doc
end

{"_id"=>BSON::ObjectId('...'), "name"=>"Akamai Technologies", "permalink"=>"akamai-technologies",
"crunchbase_url"=>"http://www.crunchbase.com/company/akamai-technologies",
"homepage_url"=>"http://www.akamai.com", ...}
{"_id"=>BSON::ObjectId('...'), "name"=>"Yodle", "permalink"=>"yodle",
"crunchbase_url"=>"http://www.crunchbase.com/company/yodle",
"homepage_url"=>"http://www.yodle.com", ...}

For a full list of options, see the API documentation for the find method.

API Documentation

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

• find

• Mongo::Collection::View

• Mongo::Cursor