/ /

Kotlin Coroutine Driver

Docs Home

Client Libraries

Kotlin

Kotlin Coroutine Driver

Docs Home

Client Libraries

Kotlin

Kotlin Coroutine Driver

Find Documents

Overview

In this guide, you can learn how to use the Kotlin driver to retrieve data from a MongoDB collection by using read operations. You can call the find() method to retrieve documents that match a set of criteria specified in a query filter.

Sample Data

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

The following Kotlin data class models the documents in this collection:

data class Movie(val title: String, val runtime: Int, val imdb: IMDB){
    data class IMDB(val rating: Double)
}

The following Kotlin data class models the results returned by the examples in this guide:

data class Results(val title: String)

Find Operation

The find() method retrieves documents from a collection. This method takes a query filter and returns all matching documents. A query filter is a document that specifies the criteria that the driver uses to match documents from the collection.

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

Find One Document Example

The following example chains the firstOrNull() method to the find() method call to find the first document in which the value of the name field is "The Room":

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)
    .firstOrNull()
if (resultsFlow == null) {
    println("No results found.");
} else {
    println(resultsFlow)
}

Movie(title=The Room, runtime=99, imdb=IMDB(rating=3.7))

Find Documents Example

This example uses the find() method to find all documents in which the value of the runtime field is less than 15. The find() operation returns a FindFlow object, which you can iterate through by using the collect() method, as shown in the following example:

val projectionFields= Projections.fields(
    Projections.include(Movie::title.name, Movie::imdb.name),
    Projections.excludeId()
)
val resultsFlow = collection.withDocumentClass<Results>()
    .find(lt(Movie::runtime.name, 15))
    .projection(projectionFields)
resultsFlow.collect { println(it) }

Movie(title=Meshes of the Afternoon, runtime=14, imdb=IMDB(rating=8.0))
Movie(title=The Band Concert, runtime=9, imdb=IMDB(rating=7.9))
Movie(title=What's Opera, Doc?, runtime=7, imdb=IMDB(rating=8.3))
...

Note

Find All Documents

To find all documents in a collection, pass an empty filter to the find() method:

val resultsFlow = collection.withDocumentClass<Results>()
    .find()

Modify Find Behavior

You can modify the behavior of the find() method by chaining methods to a FindFlow instance. The following table describes commonly used methods for modifying queries:

Method	Description
`batchSize()`	Limits the number of documents to return per batch. To learn more about batch size, see cursor.batchSize() in the MongoDB Server manual.
`collation()`	Sets the collation options for the query.
`collect()`	Processes each element in the flow and applies the given lambda.
`comment()`	Specifies a string to attach to the query. This can help you trace and interpret the operation in the server logs and in profile data.
`first()`	Returns the first document that matches the query or throws a `MongoClientException` if no matching documents exist.
`firstOrNull()`	Returns the first document that matches the query or `null` if no matching documents exist.
`hint()`	Specifies the index to use for the query.
`limit()`	Limits the number of documents to be returned from the query.
`skip()`	Sets the number of documents to skip.
`sort()`	Defines the sort criteria to apply to the query.

The following example chains the limit() method to limit the number of documents returned by the query to 10:

val projectionFields= Projections.fields(
    Projections.include(Movie::title.name, Movie::imdb.name),
    Projections.excludeId()
)
val resultsFlow = collection.withDocumentClass<Results>()
    .find()
    .projection(projectionFields)
    .limit(10)

For a full list of methods that modify the behavior of find(), see the FindFlow class in the Kotlin driver API documentation.

Additional Information

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

API Documentation

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

Back

Insert Documents

Specify Documents to Return