> This page location: /docs.md > /docs/drivers.md > /docs/languages/ruby.md > /docs/ruby-driver/current.md > /docs/ruby-driver/current/crud/query.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Find Documents

## Overview

In this guide, you can learn how to use the Ruby driver to retrieve data from a MongoDB collection by using **read operations**. You can call the `find` method on a collection to retrieve documents that match a set of criteria.

### Sample Data

The examples in this guide use the `companies` collection in the `sample_training` database from the [Atlas sample datasets](https://www.mongodb.com/docs/atlas/sample-data/). 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:

```ruby
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 [MongoDB Get Started](https://www.mongodb.com/docs/get-started/?language=ruby) guide.

## Find Documents

To retrieve documents from a collection, use the `find` method. This method takes a **query filter** parameter and returns a `Mongo::Collection::View` object, which represents the query. The driver defers the query execution until you fetch the results by using methods like `first` or `each`. After you request the results, the driver sends the query to the server and returns a `Mongo::Cursor` object from which you can access the results.

You can chain option methods to the `find` method to refine the results of the operation.

**Tip:**

To learn more about query filters, see the [Specify a Query](https://www.mongodb.com/docs/ruby-driver/current/crud/query/specify-a-query.md#std-label-ruby-specify-query) 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`:

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

```ruby
results.each do |doc|
  puts doc
end
```

**Output:**

```text
{"_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", ...}
```

**Note: Find All Documents**

To find all documents in a collection, call the `find` method without passing a query filter:

```ruby
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'`:

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

**Output:**

```text
{"_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",
...}
```

**Tip: Sort Order**

The `first` method returns the first document in [natural order](https://www.mongodb.com/docs/manual/reference/glossary/#std-term-natural-order) on disk if no sort criteria is specified.

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

| Option | Description |
| --- | --- |
| `batch_size` | The number of documents to return per batch. The default value is `101`.**Type**: `Integer` |
| `collation` | The collation to use for the operation. The default value is the collation specified for the collection.**Type**: `Hash` |
| `comment` | The comment to attach to the operation.**Type**: `Object` |
| `limit` | The maximum number of documents the operation can return.**Type**: `Integer` |
| `skip` | The number of documents to skip before returning results.**Type**: `Integer` |
| `sort` | The order in which the operation returns matching documents.**Type**: `Hash` |

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:

```ruby
limit_results = collection.find(number_of_employees: 1000).limit(2)

limit_results.each do |doc|
  puts doc
end
```

**Output:**

```text
{"_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](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection.html#find-instance_method) method.

## Additional Information

To learn more about query filters, see the [Specify a Query](https://www.mongodb.com/docs/ruby-driver/current/crud/query/specify-a-query.md#std-label-ruby-specify-query) guide.

To view code examples that retrieve documents by using the Ruby driver, see [Query Documents.](https://www.mongodb.com/docs/ruby-driver/current/crud/query.md#std-label-ruby-read)

### API Documentation

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

- [find](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection.html#find-instance_method)

- [Mongo::Collection::View](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Collection/View.html)

- [Mongo::Cursor](https://www.mongodb.com/docs/ruby-driver/current/api/Mongo/Cursor.html)
