db.collection.find()

Open Interactive Tutorial

Embedded Field Specification

For fields in an embedded documents, you can specify the field using either:

• dot notation, for example "field.nestedfield": <value>

• nested form, for example { field: { nestedfield: <value> } }

_id Field Projection

The _id field is included in the returned documents by default unless you explicitly specify _id: 0 in the projection to suppress the field.

Inclusion or Exclusion

A projection cannot contain both include and exclude specifications, with the exception of the _id field:

• In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude.

• In projections that explicitly excludes fields, the _id field is the only field that you can explicitly include; however, the _id field is included by default.

See Projection Examples.

Session Idle Timeout

MongoDB drivers and mongosh associate all operations with a server session, with the exception of unacknowledged write operations. For operations not explicitly associated with a session (i.e. using Mongo.startSession()), MongoDB drivers and mongosh create an implicit session and associate it with the operation.

If a session is idle for longer than 30 minutes, the MongoDB server marks that session as expired and may close it at any time. When the MongoDB server closes the session, it also kills any in-progress operations and open cursors associated with the session. This includes cursors configured with noCursorTimeout() or a maxTimeMS() greater than 30 minutes.

For operations that may be idle for longer than 30 minutes, associate the operation with an explicit session using Mongo.startSession() and periodically refresh the session using the refreshSessions command. See Session Idle Timeout for more information.

Query for Equality

• The following operation returns documents in the bios collection where _id equals 5:

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

• The following operation returns documents in the bios collection where the field last in the name embedded document equals "Hopper":

  db.bios.find( { "name.last": "Hopper" } )

  Note

  To access fields in an embedded document, use dot notation ("<embedded document>.<field>").

Query Using Operators

To find documents that match a set of selection criteria, call find() with the <criteria> parameter.

MongoDB provides various query operators to specify the criteria.

• The following operation uses the $in operator to return documents in the bios collection where _id equals either 5 or ObjectId("507c35dd8fada716c89d0013"):

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

• The following operation uses the $gt operator returns all the documents from the bios collection where birth is greater than new Date('1950-01-01'):

  db.bios.find( { birth: { $gt: new Date('1950-01-01') } } )

• The following operation uses the $regex operator to return documents in the bios collection where name.last field starts with the letter N (or is "LIKE N%")

  db.bios.find(
     { "name.last": { $regex: /^N/ } }
  )

For a list of the query operators, see Query Selectors.

Query for Ranges

Combine comparison operators to specify ranges for a field. The following operation returns from the bios collection documents where birth is between new Date('1940-01-01') and new Date('1960-01-01') (exclusive):

db.bios.find( { birth: { $gt: new Date('1940-01-01'), $lt: new Date('1960-01-01') } } )

For a list of the query operators, see Query Selectors.

Query for Multiple Conditions

The following operation returns all the documents from the bios collection where birth field is greater than new Date('1950-01-01') and death field does not exists:

db.bios.find( {
   birth: { $gt: new Date('1920-01-01') },
   death: { $exists: false }
} )

For a list of the query operators, see Query Selectors.

Query Exact Matches on Embedded Documents

The following operation returns documents in the bios collection where the embedded document name is exactly { first: "Yukihiro", last: "Matsumoto" }, including the order:

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

The name field must match the embedded document exactly. The query does not match documents with the following name fields:

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

Query Fields of an Embedded Document

The following operation returns documents in the bios collection where the embedded document 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 an embedded document:

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

The query matches the document where the name field contains an embedded document 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"
}

For more information and examples, see also Query on Embedded/Nested Documents.

Query for an Array Element

The following examples query the contribs array in the bios collection.

• The following operation returns documents in the bios collection where the array field contribs contains the element "UNIX":

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

• The following operation returns documents in the bios collection where the array field contribs contains the element "ALGOL" or "Lisp":

  db.bios.find( { contribs: { $in: [ "ALGOL", "Lisp" ]} } )

• The following operation use the $all query operator to return documents in the bios collection where the array field contribs contains both the elements "ALGOL" and "Lisp":

  db.bios.find( { contribs: { $all: [ "ALGOL", "Lisp" ] } } )

  For more examples, see $all. See also $elemMatch.

• The following operation uses the $size operator to return documents in the bios collection where the array size of contribs is 4:

  db.bios.find( { contribs: { $size: 4 } } )

For more information and examples of querying an array, see:

• Query an Array

• Query an Array of Embedded Documents

For a list of array specific query operators, see Array.

Query an Array of Documents

The following examples query the awards array in the bios collection.

• The following operation returns documents in the bios collection where the awards array contains an element with award field equals "Turing Award":

  db.bios.find(
     { "awards.award": "Turing Award" }
  )

• The following operation returns documents in the bios collection where the awards array contains at least one element with both the award field equals "Turing Award" and the year field greater than 1980:

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

  Use the $elemMatch operator to specify multiple criteria on an array element.

For more information and examples of querying an array, see:

• Query an Array

• Query an Array of Embedded Documents

For a list of array specific query operators, see Array.

Specify the Fields to Return

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

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

Explicitly Excluded Fields

The following operation queries the bios collection and returns all fields except the first field in the name embedded document and the birth field:

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

Explicitly Exclude the _id Field

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

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

On Arrays and Embedded Documents

The following operation queries the bios collection and returns the last field in the name embedded document and the first two elements in the contribs array:

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

You can also specify embedded fields using the nested form. For example:

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

Use Aggregation Expression

db.collection.find() projection can accept aggregation expressions and syntax.

With the use of aggregation expressions and syntax, you can project new fields or project existing fields with new values. For example, the following operation uses aggregation expressions to override the value of the name and awards fields as well as to include new fields reportDate, reportBy, and reportNumber.

db.bios.find(
   { },
   {
     _id: 0,
     name: {
        $concat: [
           { $ifNull: [ "$name.aka", "$name.first" ] },
           " ",
           "$name.last"
        ]
     },
     birth: 1,
     contribs: 1,
     awards: { $cond: { if: { $isArray: "$awards" }, then: { $size: "$awards" }, else: 0 } },
     reportDate: { $dateToString: {  date: new Date(), format: "%Y-%m-%d" } },
     reportBy: "hellouser123",
     reportNumber: { $literal: 1 }
   }
)

To set the reportRun field to the value 1 The operation returns the following documents:

{ "birth" : ISODate("1924-12-03T05:00:00Z"), "contribs" : [ "Fortran", "ALGOL", "Backus-Naur Form", "FP" ], "name" : "John Backus", "awards" : 4, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1927-09-04T04:00:00Z"), "contribs" : [ "Lisp", "Artificial Intelligence", "ALGOL" ], "name" : "John McCarthy", "awards" : 3, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1906-12-09T05:00:00Z"), "contribs" : [ "UNIVAC", "compiler", "FLOW-MATIC", "COBOL" ], "name" : "Grace Hopper", "awards" : 4, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1926-08-27T04:00:00Z"), "contribs" : [ "OOP", "Simula" ], "name" : "Kristen Nygaard", "awards" : 3, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1931-10-12T04:00:00Z"), "contribs" : [ "OOP", "Simula" ], "name" : "Ole-Johan Dahl", "awards" : 3, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1956-01-31T05:00:00Z"), "contribs" : [ "Python" ], "name" : "Guido van Rossum", "awards" : 2, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1941-09-09T04:00:00Z"), "contribs" : [ "UNIX", "C" ], "name" : "Dennis Ritchie", "awards" : 3, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1965-04-14T04:00:00Z"), "contribs" : [ "Ruby" ], "name" : "Matz Matsumoto", "awards" : 1, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "birth" : ISODate("1955-05-19T04:00:00Z"), "contribs" : [ "Java" ], "name" : "James Gosling", "awards" : 2, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }
{ "contribs" : [ "Scala" ], "name" : "Martin Odersky", "awards" : 0, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 }

With Variable Name

The following example uses the variable myCursor to iterate over the cursor and print the matching documents:

var myCursor = db.bios.find( );
myCursor

With next() Method

The following example uses the cursor method next() to access the documents:

var myCursor = db.bios.find( );
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

The following example uses the cursor method forEach() to iterate the cursor and access the documents:

var myCursor = db.bios.find( );
myCursor.forEach(printjson);

Order Documents in the Result Set

The sort() method orders the documents in the result set. The following operation returns documents in the bios collection sorted in ascending order by the name field:

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 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 skips the first 5 documents in the bios collection and returns all remaining documents:

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

Specify Collation

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The collation() method specifies the collation for the db.collection.find() operation.

db.bios.find( { "name.last": "hopper" } ).collation( { locale: "en_US", strength: 1 } )

Combine Cursor Methods

The following statements chain cursor methods limit() and sort():

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

The two statements are equivalent; i.e. the order in which you chain the limit() and the sort() methods is not significant. Both statements return the first five documents, as determined by the ascending sort order on 'name'.

Available mongosh Cursor Methods

limit with options

The following query limits the number of documents in the result set with the limit options parameter:

db.users.find(
   { username : "rajiv"}, // query
   { age : 1 }, // projection
   { limit : 1 } // options
)

allowDiskUse with options

The following query uses the options parameter to enable allowDiskUse:

db.users.find(
   { username : "david" },
   { age : 1 },
   { allowDiskUse : true }
)

explain with options

The following query uses the options parameter to get the executionStats explain output:

var cursor = db.users.find(
   { username: "amanda" },
   { age : 1 },
   { explain : "executionStats" }
)
cursor.next()

Specify Multiple options in a query

The following query uses multiple options in a single query. This query uses limit set to 2 to return only two documents, and showRecordId set to true to return the position of the document in the result set:

db.users.find(
   {},
   { username: 1, age: 1 },
   {
     limit: 2,
     showRecordId: true
   }
)