Retrieve Data

On this page

Overview

Sample Data
Find Documents
Find One Document
Find Multiple Documents
Modify Find Behavior
Additional Information
API Documentation

Overview

In this guide, you can learn how to use the MongoDB Java Reactive Streams Driver to retrieve data from a MongoDB collection by using read operations.

Sample Data

The examples in this guide use the sample_restaurants.restaurants collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started.

Important

Project Reactor Library

This guide uses the Project Reactor library to consume Publisher instances returned by the Java Reactive Streams driver methods. To learn more about the Project Reactor library and how to use it, see Getting Started in the Reactor documentation. To learn more about how we use Project Reactor library methods in this guide, see the Write Data to MongoDB guide.

Find Documents

The Java Reactive Streams driver includes one method for retrieving documents from a collection: find().

This method takes a query filter and returns one or more matching documents. A query filter is an object that specifies the documents you want to retrieve in your query.

To learn more about query filters, see the Specify a Query guide.

Find One Document

To find a single document in a collection, chain the first() method to your find() method call and pass a query filter to the find() method call that specifies the criteria of the document you want to find. If more than one document matches the query filter, the find().first() construct returns the first matching document from the retrieved results. If no documents match the query filter, the construct returns None.

Tip

The find().first() construct is useful when you know there's only one matching document, or you're interested only in the first match.

The following example uses the find().first() construct to find the first document where the "cuisine" field has the value "Bakery":

Publisher<Document> findDocPublisher = restaurants.find(
    eq("cuisine", "Bakery")).first();
Mono.from(findDocPublisher)
        .doOnNext(System.out::println)
        .blockLast();

Tip

Sort Order

If you do not specify a sort order, the find().first() construct returns the first document in natural order on disk.

To learn more about sorting, see the Specify Documents to Return guide.

Find Multiple Documents

To find multiple documents in a collection, pass a query filter to the find() method that specifies the criteria of the documents you want to retrieve.

The following example uses the find() method to find all documents where the "cuisine" field has the value "Spanish":

FindPublisher<Document> findDocPublisher = restaurants.find(
        eq("cuisine", "Spanish"));
Flux.from(findDocPublisher)
        .doOnNext(System.out::println)
        .blockLast();

Note

Find All Documents

To find all documents in a collection, pass no parameters to the find() method:

Publisher<Document> findAllPublisher = restaurants.find();
Flux.from(findAllPublisher)
        .doOnNext(System.out::println)
        .blockLast();

Modify Find Behavior

You can modify the behavior of the find() method by chaining other methods to it. The following table describes commonly used methods:

Argument	Description
`batchSize(int batchSize)`	The maximum number of documents within each batch returned in a query result. By default, the `find` command has an initial batch size of `101` documents and a maximum size of 16 mebibytes (MiB) for each subsequent batch. This option can enforce a smaller limit than 16 MiB, but not a larger one. If you set `batchSize` to a limit that results in batches larger than 16 MiB, this option has no effect. A `batchSize` of `0` means that the cursor will be established, but no documents will be returned in the first batch.
`collation(Collation collation)`	Sets the collation options as an instance of the `Collation` class.
`comment(String comment)`	Attaches a string to the query. This can help you trace and interpret the operation in the server logs and in profile data. To learn more about query comments, see the cursor.comment() page in the MongoDB Server manual.
`hint(Bson hint)`	Gets or sets the index to scan for documents. For more information, see the hint statement in the MongoDB Server manual.

The following example uses the find() method to find all documents where the "cuisine" field has the value "Italian" and sets a comment:

FindPublisher<Document> findDocPublisher = restaurants.find(
        eq("cuisine", "Italian")).comment("Find operation");
Flux.from(findDocPublisher)
        .doOnNext(System.out::println)
        .blockLast();

For a full list of available arguments, see the API documentation for the FindPublisher interface.

Additional Information

To learn more about query filters, see the Specify a Query guide.

For runnable code examples of retrieving documents by using the Java Reactive Streams driver, see the Read Data guide.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Query

Specify Fields to Return