Find a Document

You can query for a single document in a collection with the collection.findOne() method. The findOne() method uses a query document that you provide to match only the subset of the documents in the collection that match the query. If you don't provide a query document or if you provide an empty document, MongoDB matches all documents in the collection. The findOne() operation only returns the first matched document. For more information on querying MongoDB, see our documentation on query documents.

You can also define more query options such as sort and projection to configure the returned document. You can specify the more options in the options object passed as the second parameter of the findOne method. For detailed reference documentation, see collection.findOne().

Compatibility

You can use the Node.js driver to connect and use the findOne() method for deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

To learn more about finding documents in the Atlas UI for deployments hosted in MongoDB Atlas, see Create, View, Update, and Delete Documents.

Example

The following snippet finds a single document from the movies collection. It uses the following parameters:

A query document that configures the query to return only movies with the title of exactly the text 'The Room'.
A sort that organizes matched documents in descending order by rating, so if our query matches multiple documents the returned document will be the document with the highest rating.
A projection that explicitly excludes the _id field from returned documents and explicitly includes only the title and imdb object (and its embedded fields).

Note

You can use this example to connect to an instance of MongoDB and interact with a database that contains sample data. To learn more about connecting to your MongoDB instance and loading a sample dataset, see the Usage Examples guide.

import { MongoClient } from "mongodb";
// Replace the uri string with your MongoDB deployment's connection string.
const uri = "<connection string uri>";
const client = new MongoClient(uri);
async function run() {
  try {
    
    // Get the database and collection on which to run the operation
    const database = client.db("sample_mflix");
    const movies = database.collection("movies");
    // Query for a movie that has the title 'The Room'
    const query = { title: "The Room" };
    const options = {
      // Sort matched documents in descending order by rating
      sort: { "imdb.rating": -1 },
      // Include only the `title` and `imdb` fields in the returned document
      projection: { _id: 0, title: 1, imdb: 1 },
    };
    // Execute query
    const movie = await movies.findOne(query, options);
    // Print the document returned by findOne()
    console.log(movie);
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

import { MongoClient } from "mongodb";
// Replace the uri string with your MongoDB deployment's connection string.
const uri = "<connection string uri>";
const client = new MongoClient(uri);
interface IMDB {
  rating: number;
  votes: number;
  id: number;
}
export interface Movie {
  title: string;
  year: number;
  released: Date;
  plot: string;
  type: "movie" | "series";
  imdb: IMDB;
}
type MovieSummary = Pick<Movie, "title" | "imdb">;
async function run(): Promise<void> {
  try {
    const database = client.db("sample_mflix");
    // Specifying a Schema is always optional, but it enables type hinting on
    // finds and inserts
    const movies = database.collection<Movie>("movies");
    const movie = await movies.findOne<MovieSummary>(
      { title: "The Room" },
      {
        sort: { rating: -1 },
        projection: { _id: 0, title: 1, imdb: 1 },
      }
    );
    console.log(movie);
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

Running the preceding example, you see the following output:

{ title: 'The Room', imdb: { rating: 3.5, votes: 25673, id: 368226 } }

Back

Find Operations

Find Multiple Documents