collection.findOne(query, projection)

Returns one document that satisfies the specified query criteria on the collection or view. If multiple documents satisfy the query, this method returns the first document according to the natural order. If no document satisfies the query, the method returns undefined.

Parameter Type Description
query document

Optional. Specifies selection filter using query selectors.

Specify an empty document { } or omit this parameter to return the first document in the collection.

projection document Optional. Specifies the fields to return in the documents that match the query filter. To return all fields in the matching documents, specify an empty document { } or omit this parameter. See Projection Operators for all available projection operators.
Returns:A promise that resolves to exactly one document matching the query pattern or to undefined. If you specify a projection parameter, collection.findOne() returns a document that only contains the projection fields. The _id field is always included unless you explicitly exclude it.


Working with BSON

MongoDB actions may return documents containing BSON types.

Assume the collection test.example contains the following document.

  "_id": ObjectId("5a0c516ac7ecd33f1aea0915"),
  "binary_data": BinData(0,"ymz="),
  "owner_id": "5b1574258f25b9240ed8f8bb"

When this document is retrieved in Stitch, _id is represented by a BSON.ObjectId type and binary_data is represented as a BSON.Binary type.

The following example shows how a MongoDB Stitch function can manipulate these types.

exports = function() {
  const mongodb ="mongodb-atlas");
  const collection = mongodb.db("test").collection("example");

  return collection
    .then(doc => {
      const asBase64 = doc.binary_data.toBase64();
      const asOidString = doc._id.toString();
      return { asBase64, asOidString }

For more information on manipulating BSON in Stitch, see BSON.


The following examples assume that the test.example namespace has been added to MongoDB in the Stitch admin console and appropriate rules have been set. See MongoDB Rules for more information.

Finding the First Document in a Collection

exports = function() {
    const mongodb ="mongodb-atlas");
    const collection = mongodb.db("test").collection("example");
    return collection.findOne();

Finding a Document Matching User Input

Assume the test.example collection contains the following documents:

{ "username": "user1", "zip": "08691", "_id": ObjectId("5a0c516ac7ecd33f1aea0915") }
{ "username": "user2", "zip": "10022", "_id": ObjectId("5a0c516ac7ecd33f1aea0916") }

Assume the Stitch app contains a function named select_zip with the following definition:

exports = function(uname) {
    const mongodb ="mongodb-atlas");
    const collection = mongodb.db("test").collection("example");
    return collection.findOne({"username": uname}, {"_id": 0});

The function select_zip return a document with the username matching the argument. The call to collection.findOne() also projects to remove the _id field from the returned document.

Clients may call this function by referring to it by name. The following example calls the function from the Javascript SDK:

stitchClient.executeFunction("select_zip", "user1")
    .then((document) => console.log(document));

This outputs:

{ "username": "user1", zip: "08691" }

Finding a Document Matching a Regular Expression

Regular expressions must be encoded to BSON.

exports = function() {
  const mongodb ="mongodb-atlas");
  const coll = mongodb.db("test").collection("example");

  const regex = BSON.BSONRegExp("com\.domain\..+", "i")
  return coll.findOne({ "package": { "$regex": regex } });