- Reference >
- mongo Shell Methods >
- Collection Methods >
- db.collection.findOne()
db.collection.findOne()¶
Definition¶
- db.collection.findOne(<criteria>, <projection>)¶
Returns one document that satisfies the specified query criteria. If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk. In capped collections, natural order is the same as insertion order.
Parameter Type Description criteria document Optional. Specifies query selection criteria using query operators. projection document Optional. Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document.
The projection parameter takes a document of the following form:
{ field1: <boolean>, field2: <boolean> ... }
The <boolean> can be one of the following include or exclude values:
- 1 or true to include. The findOne() method always includes the _id field even if the field is not explicitly specified in the projection parameter.
- 0 or false to exclude.
The projection argument cannot mix include and exclude specifications, with the exception of excluding the _id field.
returns: One document that satisfies the criteria specified as the first argument to this method. If you specify a projection parameter, findOne() returns a document that only contains the projection fields. The _id field is always included unless you explicitly exclude it.
Although similar to the find() method, the findOne() method returns a document rather than a cursor.
Examples¶
With Empty Query Specification¶
The following operation returns a single document from the bios collection:
db.bios.findOne()
With a Query Specification¶
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¶
The projection parameter specifies which fields to return. The parameter contains either include or exclude specifications, not both, unless the exclude is for the _id field.
Specify the Fields to Return¶
The following operation finds a document in the bios collection and returns only the name, contribs and _id fields:
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:
db.bios.findOne(
{ contribs: 'OOP' },
{ _id: 0, 'name.first': 0, birth: 0 }
)
The findOne Result Document¶
You cannot apply cursor methods to the result of findOne() because a single document is returned. You have access to the document directly:
var myDocument = db.bios.findOne();
if (myDocument) {
var myName = myDocument.name;
print (tojson(myName));
}