Navigation

collection.findOne()

Definition

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:One document that satisfies the criteria specified as the first argument to this method or 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.

Behavior

Working with BSON

MongoDB service actions may return documents containing BSON types.

Assume the collection test.example contains the following document.

{ "_id": ObjectId("5a0c516ac7ecd33f1aea0915"), "binary_data": BinData(0,"ymz=") }

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() {
    var coll = context.services.get("mongodb-atlas").db("test").collection("example");
    var doc = coll.findOne();
    var asBase64 = doc.binary_data.toBase64();
    var asOidString = doc._id.toString();
    return [asBase64, asOidString];
}

For more information on manipulating BSON in Stitch, see :ref :bson-in-stitch.

Examples

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

Returning the First Document in a Collection

exports = function() {
    var mongodb = context.services.get("mongodb-atlas");
    var coll = mongodb.db("test").collection("example");
    return coll.findOne();
};

Returning Documents 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) {
    var mongodb = context.services.get("mongodb-atlas");
    var coll = mongodb.db("test").collection("example");
    return coll.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" }