Specify Documents to Return

Overview

In this guide, you can learn how to specify which documents to return from a read operation by using the following methods:

• limit(): Specifies the maximum number of documents to return from a query

• sort(): Specifies the sort order for the returned documents

• skip(): Specifies the number of documents to skip before returning query results

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String
)

Limit

To specify the maximum number of documents returned from a read operation, call the limit() method.

The following example finds all restaurants that have a cuisine field value of "Italian" and limits the results to 5 documents:

val results = collection
    .find(eq(Restaurant::cuisine.name, "Italian"))
    .limit(5)
results.forEach { result ->
    println(result)
}

Restaurant(name=Philadelphia Grille Express, borough=Brooklyn, cuisine=Italian)
Restaurant(name=Isle Of Capri Resturant, borough=Manhattan, cuisine=Italian)
Restaurant(name=Marchis Restaurant, borough=Manhattan, cuisine=Italian)
Restaurant(name=Crystal Room, borough=Staten Island, cuisine=Italian)
Restaurant(name=Forlinis Restaurant, borough=Manhattan, cuisine=Italian)

Sort

To return documents in a specified order, call the sort() method. The sort() method takes a sort direction as a parameter. To specify the sort direction, use the Sorts.ascending() or Sorts.descending() method. The Sorts.ascending() method sorts values from lowest to highest, and the Sorts.descending() method sorts values from highest to lowest. If you don't specify a sort direction, sort() returns the documents in ascending order.

The following example returns all documents with a cuisine field value of "Italian", sorted by the value of the name field in ascending order:

val results = collection
    .find(eq(Restaurant::cuisine.name, "Italian"))
    .sort(Sorts.ascending(Restaurant::name.name))
results.forEach { result ->
    println(result)
}

Restaurant(name=(Lewis Drug Store) Locanda Vini E Olii, borough=Brooklyn, cuisine=Italian)
Restaurant(name=101 Restaurant And Bar, borough=Brooklyn, cuisine=Italian)
Restaurant(name=44 Sw Ristorante & Bar, borough=Manhattan, cuisine=Italian)
Restaurant(name=900 Park, borough=Bronx, cuisine=Italian)
Restaurant(name=A Voce, borough=Manhattan, cuisine=Italian)
...

Skip

To skip a specified number of documents before returning your query results, call the skip() method and pass in the number of documents to skip. The skip() method ignores the specified number of documents in your query results and returns the rest.

The following example returns all documents that have a cuisine field value of "Italian" and skips the first 10 documents:

val results = collection
    .find(eq(Restaurant::cuisine.name, "Italian"))
    .skip(10)
results.forEach { result ->
    println(result)
}

Restaurant(name=San Pietro, borough=Manhattan, cuisine=Italian)
Restaurant(name=Manetta's Ristorante, borough=Queens, cuisine=Italian)
Restaurant(name=Salvi Restaurant, borough=Brooklyn, cuisine=Italian)
Restaurant(name=Tommaso Restaurant, borough=Brooklyn, cuisine=Italian)
Restaurant(name=Da Rosina Restaurant, borough=Manhattan, cuisine=Italian)
...

Combine Limit, Sort, and Skip

You can combine the limit(), sort(), and skip() methods in a single operation. This allows you to set a maximum number of sorted documents to return, skipping a specified number of documents before returning.

The following example returns documents with the cuisine field value of "Italian". The results are sorted in alphabetical order, skipping the first 10 documents and limiting the results to 5 documents:

val results = collection
    .find(eq(Restaurant::cuisine.name, "Italian"))
    .sort(Sorts.ascending(Restaurant::name.name))
    .skip(10)
    .limit(5)
results.forEach { result ->
    println(result)
}

Restaurant(name=Acqua, borough=Manhattan, cuisine=Italian)
Restaurant(name=Acqua Restaurant, borough=Manhattan, cuisine=Italian)
Restaurant(name=Acqua Santa, borough=Brooklyn, cuisine=Italian)
Restaurant(name=Acquista Trattoria, borough=Queens, cuisine=Italian)
Restaurant(name=Acquolina Catering, borough=Manhattan, cuisine=Italian)

Additional Information

For more information about specifying a query, see Specify a Query.

For more information about retrieving documents, see Retrieve Data.