Retrieve Data
On this page
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) | Limits the number of documents to hold in a cursor at a given time. To
learn more about cursors, see cursor in the MongoDB Server documentation. |
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 $comment page. |
hint(Bson hint) | Gets or sets the index to scan for documents.
For more information, see the hint statement
in the MongoDB Server manual. |
maxTime(long maxTime, TimeUnit timeUnit) | Sets the maximum execution time on the server for this operation. If this time is
exceeded, the Java Reactive Streams driver aborts the operation and raises an ExecutionTimeout. |
The following example uses the find() method to find all documents where
the "cuisine" field has the value "Italian" and sets a maximum execution
time of 10 seconds:
FindPublisher<Document> findDocPublisher = restaurants.find( eq("cuisine", "Italian")).maxTime(10L, TimeUnit.SECONDS); 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 From MongoDB guide.
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API documentation: