Navigation

This version of the documentation is archived and no longer supported.

Core MongoDB Operations (CRUD) >
Read

Read¶

On this page

Overview
find()
findOne()

Of the four basic database operations (i.e. CRUD), read operations are those that retrieve records or documents from a collection in MongoDB. For general information about read operations and the factors that affect their performance, see Read Operations; for documentation of the other CRUD operations, see the Core MongoDB Operations (CRUD) page.

Overview¶

You can retrieve documents from MongoDB using either of the following methods:

find
findOne

`find()`¶

The find() method is the primary method to select documents from a collection. The find() method returns a cursor that contains a number of documents. Most drivers provide application developers with a native iterable interface for handling cursors and accessing documents. The find() method has the following syntax:

db.collection.find( <query>, <projection> )

Corresponding Operation in SQL

The find() method is analogous to the SELECT statement, while:

the <query> argument corresponds to the WHERE statement, and
the <projection> argument corresponds to the list of fields to select from the result set.

The examples refer to a collection named bios that contains documents with the following prototype:

{
  "_id" : 1,
  "name" : {
             "first" : "John",
             "last" :"Backus"
           },
  "birth" : ISODate("1924-12-03T05:00:00Z"),
  "death" : ISODate("2007-03-17T04:00:00Z"),
  "contribs" : [ "Fortran", "ALGOL", "Backus-Naur Form", "FP" ],
  "awards" : [
              {
                "award" : "W.W. McDowellAward",
                "year" : 1967,
                "by" : "IEEE Computer Society"
              },
              {
                "award" : "National Medal of Science",
                "year" : 1975,
                "by" : "National Science Foundation"
              },
              {
                "award" : "Turing Award",
                "year" : 1977,
                "by" : "ACM"
              },
              {
                "award" : "Draper Prize",
                "year" : 1993,
                "by" : "National Academy of Engineering"
              }
  ]
}

Note

In the mongo shell, you can format the output by adding .pretty() to the find() method call.

Return All Documents in a Collection¶

If there is no <query> argument, the :method:` ~db.collection.find()` method selects all documents from a collection.

The following operation returns all documents (or more precisely, a cursor to all documents) in the bios collection:

db.bios.find()

Return Documents that Match Query Conditions¶

If there is a <query> argument, the find() method selects all documents from a collection that satisfies the query specification.

Equality Matches¶

The following operation returns a cursor to documents in the bios collection where the field _id equals 5:

db.bios.find(
   {
      _id: 5
   }
)

Using Operators¶

The following operation returns a cursor to all documents in the bios collection where the field _id equals 5 or ObjectId("507c35dd8fada716c89d0013"):

db.bios.find(
   {
      _id: { $in: [ 5,  ObjectId("507c35dd8fada716c89d0013") ] }
   }
)

On Arrays¶

Query an Element¶

The following operation returns a cursor to all documents in the bios collection where the array field contribs contains the element 'UNIX':

db.bios.find(
   {
     contribs: 'UNIX'
   }
)

Query Multiple Fields on an Array of Documents¶

The following operation returns a cursor to all documents in the bios collection where awards array contains a subdocument element that contains the award field equal to 'Turing Award' and the year field greater than 1980:

db.bios.find(
   {
      awards: {
                $elemMatch: {
                     award: 'Turing Award',
                     year: { $gt: 1980 }
                }
      }
   }
)

On Subdocuments¶

Exact Matches¶

The following operation returns a cursor to all documents in the bios collection where the subdocument name is exactly { first: 'Yukihiro', last: 'Matsumoto' }, including the order:

db.bios.find(
    {
      name: {
              first: 'Yukihiro',
              last: 'Matsumoto'
            }
    }
)

The name field must match the sub-document exactly, including order. For instance, the query would not match documents with name fields that held either of the following values:

{
   first: 'Yukihiro',
   aka: 'Matz',
   last: 'Matsumoto'
}

{
   last: 'Matsumoto',
   first: 'Yukihiro'
}

Fields of a Subdocument¶

The following operation returns a cursor to all documents in the bios collection where the subdocument name contains a field first with the value 'Yukihiro' and a field last with the value 'Matsumoto'; the query uses dot notation to access fields in a subdocument:

db.bios.find(
   {
     'name.first': 'Yukihiro',
     'name.last': 'Matsumoto'
   }
)

The query matches the document where the name field contains a subdocument with the field first with the value 'Yukihiro' and a field last with the value 'Matsumoto'. For instance, the query would match documents with name fields that held either of the following values:

{
  first: 'Yukihiro',
  aka: 'Matz',
  last: 'Matsumoto'
}

{
  last: 'Matsumoto',
  first: 'Yukihiro'
}

Logical Operators¶

`OR` Disjunctions¶

The following operation returns a cursor to all documents in the bios collection where either the field first in the sub-document name starts with the letter G or where the field birth is less than new Date('01/01/1945'):

db.bios.find(
   { $or: [
            { 'name.first' : /^G/ },
            { birth: { $lt: new Date('01/01/1945') } }
          ]
   }
)

`AND` Conjunctions¶

The following operation returns a cursor to all documents in the bios collection where the field first in the subdocument name starts with the letter K and the array field contribs contains the element UNIX:

db.bios.find(
   {
      'name.first': /^K/,
      contribs: 'UNIX'
   }
)

In this query, the parameters (i.e. the selections of both fields) combine using an implicit logical AND for criteria on different fields contribs and name.first. For multiple AND criteria on the same field, use the $and operator.

With a Projection¶

If there is a <projection> argument, the find() method returns only those fields as specified in the <projection> argument to include or exclude:

Note

The _id field is implicitly included in the <projection> argument. In projections that explicitly include fields, _id is the only field that you can explicitly exclude. Otherwise, you cannot mix include field and exclude field specifications.

Specify the Fields to Return¶

The following operation finds all documents in the bios collection and returns only the name field, the contribs field, and the _id field:

db.bios.find(
    { },
    { name: 1, contribs: 1 }
 )

Explicitly Exclude the `_id` Field¶

The following operation finds all documents in the bios collection and returns only the name field and the contribs field:

db.bios.find(
   { },
   { name: 1, contribs: 1, _id: 0 }
)

Return All but the Excluded Fields¶

The following operation finds the documents in the bios collection where the contribs field contains the element 'OOP' and returns all fields except the _id field, the first field in the name subdocument, and the birth field from the matching documents:

db.bios.find(
   { contribs: 'OOP' },
   { _id: 0, 'name.first': 0, birth: 0 }
)

On Arrays and Subdocuments¶

The following operation finds all documents in the bios collection and returns the the last field in the name subdocument and the first two elements in the contribs array:

db.bios.find(
   { },
   {
     _id: 0,
     'name.last': 1,
     contribs: { $slice: 2 }
   }
)

See also

dot notation for information on “reaching into” embedded sub-documents.
Arrays for more examples on accessing arrays.
Subdocuments for more examples on accessing subdocuments.
$elemMatch query operator for more information on matching array elements.
$elemMatch projection operator for additional information on restricting array elements to return.

Iterate the Returned Cursor¶

The find() method returns a cursor to the results; however, in the mongo shell, if the returned cursor is not assigned to a variable, then the cursor is automatically iterated up to 20 times [1] to print up to the first 20 documents that match the query, as in the following example:

db.bios.find( { _id: 1 } );

With Variable Name¶

When you assign the find() to a variable, you can type the name of the cursor variable to iterate up to 20 times [1] and print the matching documents, as in the following example:

var myCursor = db.bios.find( { _id: 1 } );

myCursor

With `next()` Method¶

You can use the cursor method next() to access the documents, as in the following example:

var myCursor = db.bios.find( { _id: 1 } );

var myDocument = myCursor.hasNext() ? myCursor.next() : null;

if (myDocument) {
    var myName = myDocument.name;
    print (tojson(myName));
}

To print, you can also use the printjson() method instead of print(tojson()):

if (myDocument) {
   var myName = myDocument.name;
   printjson(myName);
}

With `forEach()` Method¶

You can use the cursor method forEach() to iterate the cursor and access the documents, as in the following example:

var myCursor = db.bios.find( { _id: 1 } );

myCursor.forEach(printjson);

For more information on cursor handling, see:

[1]	(1, 2) You can use the `DBQuery.shellBatchSize` to change the number of iteration from the default value `20`. See Cursor Flags and Cursor Behaviors for more information.

Modify the Cursor Behavior¶

In addition to the <query> and the <projection> arguments, the mongo shell and the drivers provide several cursor methods that you can call on the cursor returned by find() method to modify its behavior, such as:

Order Documents in the Result Set¶

The sort() method orders the documents in the result set.

The following operation returns all documents (or more precisely, a cursor to all documents) in the bios collection ordered by the name field ascending:

db.bios.find().sort( { name: 1 } )

sort() corresponds to the ORDER BY statement in SQL.

Limit the Number of Documents to Return¶

The limit() method limits the number of documents in the result set.

The following operation returns at most 5 documents (or more precisely, a cursor to at most 5 documents) in the bios collection:

db.bios.find().limit( 5 )

limit() corresponds to the LIMIT statement in SQL.

Set the Starting Point of the Result Set¶

The skip() method controls the starting point of the results set.

The following operation returns all documents, skipping the first 5 documents in the bios collection:

db.bios.find().skip( 5 )

Combine Cursor Methods¶

You can chain these cursor methods, as in the following examples [2]:

db.bios.find().sort( { name: 1 } ).limit( 5 )
db.bios.find().limit( 5 ).sort( { name: 1 } )

See the JavaScript cursor methods reference and your driver documentation for additional references. See Cursors for more information regarding cursors.

[2] Regardless of the order you chain the limit() and the sort(), the request to the server has the structure that treats the query and the :method:` ~cursor.sort()` modifier as a single object. Therefore, the limit() operation method is always applied after the sort() regardless of the specified order of the operations in the chain. See the meta query operators for more information.

`findOne()`¶

The findOne() method selects a single document from a collection and returns that document. findOne() does not return a cursor.

The findOne() method has the following syntax:

db.collection.findOne( <query>, <projection> )

Except for the return value, findOne() method is quite similar to the find() method; in fact, internally, the findOne() method is the find() method with a limit of 1.

With Empty Query Specification¶

If there is no <query> argument, the findOne() method selects just one document from a collection.

The following operation returns a single document from the bios collection:

db.bios.findOne()

With a Query Specification¶

If there is a <query> argument, the findOne() method selects the first document from a collection that meets the <query> argument:

The following operation returns the first matching document from the bios collection where either the field first in the subdocument name starts with the letter G or where the field birth is less than new Date('01/01/1945'):

db.bios.findOne(
   {
     $or: [
            { 'name.first' : /^G/ },
            { birth: { $lt: new Date('01/01/1945') } }
          ]
   }
)

With a Projection¶

You can pass a <projection> argument to findOne() to control the fields included in the result set.

Specify the Fields to Return¶

The following operation finds a document in the bios collection and returns only the name field, the contribs field, and the _id field:

db.bios.findOne(
    { },
    { name: 1, contribs: 1 }
)

Return All but the Excluded Fields¶

The following operation returns a document in the bios collection where the contribs field contains the element OOP and returns all fields except the _id field, the first field in the name subdocument, and the birth field from the matching documents:

db.bios.findOne(
   { contribs: 'OOP' },
   { _id: 0, 'name.first': 0, birth: 0 }
)

Access the `findOne` Result¶

Although similar to the find() method, because the findOne() method returns a document rather than a cursor, you cannot apply the cursor methods such as limit(), sort(), and skip() to the result of the findOne() method. However, you can access the document directly, as in the example:

var myDocument = db.bios.findOne();

if (myDocument) {
   var myName = myDocument.name;

   print (tojson(myName));
}

← Create Update →