Find a Document

You can retrieve a single document in a collection by chaining together the find() and first() methods on a MongoCollection object. You can pass a query filter to the find() method to query for and return documents that match the filter in the collection. If you do not include a filter, MongoDB returns all the documents in the collection.

For more information on querying MongoDB with the Kotlin driver, see our guide on Querying Documents.

You can also chain other methods to the find() method such as sort() which organizes the matched documents in a specified order, and projection() which configures the fields included in the returned documents.

For more information on the sort() method, see our guide on Sorting. For more information on the projection() method, see our guide on Projections

The find() method returns an instance of FindFlow, a class that offers several methods to access, organize, and traverse the results.

FindFlow also obtains methods from its delegate interface Flow from the Kotlin Coroutines library, such as first() and firstOrNull(). The firstOrNull() method returns the first document from the retrieved results or null if there are no results. The first() method returns the first document or throws a NoSuchElementException exception if no documents match the query.

For more information on accessing data from a flow with the Kotlin driver, see our guide on Accessing Data From a Flow.

Example

The following snippet finds a single document from the movies collection. It uses the following objects and methods:

A query filter that is passed to the find() method. The eq filter matches only movies with the title exactly matching 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 is the one with the highest rating.
A projection that includes the objects in the title and imdb fields and excludes the _id field using the helper method excludeId().

Note

This example connects to an instance of MongoDB using a connection URI. To learn more about connecting to your MongoDB instance, see the connection guide.

import com.mongodb.client.model.Filters.eq
import com.mongodb.client.model.Filters.lt
import com.mongodb.client.model.Projections
import com.mongodb.client.model.Sorts
import com.mongodb.kotlin.client.coroutine.MongoClient
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
import usageExamples.find.Results
data class Movie(val title: String, val runtime: Int, val imdb: IMDB) {
    data class IMDB(val rating: Double)
}
data class Results(val title: String, val imdb: Movie.IMDB)
fun main() = runBlocking {
    // Replace the uri string with your MongoDB deployment's connection string
    val uri = "<connection string uri>"
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Movie>("movies")
    val projectionFields= Projections.fields(
        Projections.include(Movie::title.name, Movie::imdb.name),
        Projections.excludeId()
    )
    val resultsFlow = collection.withDocumentClass<Results>()
        .find(eq(Movie::title.name, "The Room"))
        .projection(projectionFields)
        .sort(Sorts.descending("${Movie::imdb.name}.${Movie.IMDB::rating.name}"))
        .firstOrNull()
    if (resultsFlow == null) {
        println("No results found.");
    } else {
        println(resultsFlow)
    }
    mongoClient.close()
}

For additional information on the classes and methods mentioned on this page, see the following API Documentation:

Back

Find Operations

Find Multiple Documents