Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Search
/
Tutorials
/
Paginate Results

How to Paginate the Query Results

On this page

  • Create the Atlas Search Index With Static Mappings
  • Required Roles
  • Procedure
  • Run a Query and Paginate the Results
  • Procedure
  • Retrieve Page 1 and Generate Pagination Tokens
  • Retrieve Page 2 Using searchAfter
  • Return to Page 1 Using searchBefore
  • Jump from Page 2 to Page 5 Using searchAfter and $skip
  • Use Facet with the Paginated Results

This tutorial demonstrates how to paginate the results of your Atlas Search queries to build functions like "Next Page" and "Previous Page" in your application. It also demonstrates how to jump across pages by using $skip and $limit. This tutorial takes you through the following steps:

  1. Set up an Atlas Search index with static mappings for the sample_mflix.movies collection.

  2. Run Atlas Search queries against the indexed fields to return sequential results that allow you to do the following:

    • Traverse pages in-order to build functions like "Next Page" and "Previous Page".

    • Jump from the second to the fifth page and skip pages in the results.

    • Retrieve a count of the total number of movies in each genre in the results.

Before you begin, ensure that your Atlas cluster meets the requirements described in the Prerequisites.

Note

To use the Atlas Search $search searchSequenceToken to retrieve sequential results, your Atlas cluster must run MongoDB v6.0.13+ or v7.0.5+.

Create the Atlas Search Index With Static Mappings

In this section, you create an Atlas Search index that uses static mappings to index the fields in the sample_mflix.movies collection.

Required Roles

To create an Atlas Search index, you must have Project Data Access Admin or higher access to the project.

Procedure

1

In Atlas, go to the Clusters page for your project.

  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your desired project from the Projects menu in the navigation bar.

  3. If the Clusters page is not already displayed, click Database in the sidebar.

    The Clusters page displays.

2

Go to the Atlas Search page for your cluster.

You can go the Atlas Search page from the sidebar, the Data Explorer, or your cluster details page.

  1. In the sidebar, click Atlas Search under the Services heading.

  2. From the Select data source dropdown, select your cluster and click Go to Atlas Search.

    The Atlas Search page displays.

  1. Click the Browse Collections button for your cluster.

  2. Expand the database and select the collection.

  3. Click the Search Indexes tab for the collection.

    The Atlas Search page displays.

  1. Click the cluster's name.

  2. Click the Atlas Search tab.

    The Atlas Search page displays.

3

Click Create Search Index.

4

Select an Atlas Search Configuration Method and click Next.

  • For a guided experience, select the Atlas Search Visual Editor.

  • To edit the raw index definition, select the Atlas Search JSON Editor.

5

Enter the Index Name, and set the Database and Collection.

  1. In the Index Name field, enter pagination-tutorial.

  2. In the Database and Collection section, find the sample_mflix database, and select the movies collection.

6

Define the Atlas Search index.

The following index definition configures index for the following fields:

  • title field as the string type for full-text search against the field

  • genres field as the stringFacet type for faceted search against the field

  • released field as the date type for sorting the results using the field

You can use the Atlas Search Visual Editor or the Atlas Search JSON Editor in the Atlas user interface to create the index.

  1. Click Next.

  2. Click Refine Your Index.

  3. In the Index Configurations section, toggle to disable Dynamic Mapping.

  4. Click Add Field in the Field Mappings section and click Add after configuring the settings for the following fields, one by one, in the Add Field Mapping window Customized Configuration tab.

    Field Name
    Data Type Configuration
    title
    String
    genres
    stringFacet
    released
    Date

  5. Click Save Changes.

  1. Replace the default index definition with the following definition.

    1{
    2  "mappings": {
    3    "dynamic": false,
    4    "fields": {
    5      "title": {
    6        "type": "string"
    7      },
    8      "genres": {
    9        "type": "stringFacet"
    10      },
    11      "released": {
    12        "type": "date"
    13      }
    14    }
    15  }
    16}

  2. Click Next.

7

Click Create Search Index.

A modal window displays to let you know that your index is building.

8

Close the You're All Set! modal window by clicking Close and wait for the index to finish building.

The index should take about one minute to build. While it is building, the Status column reads Initial Sync. When it is finished building, the Status column reads Active.

Run a Query and Paginate the Results

In this section, you run queries to retrieve results for movies with the term summer in the title. In the queries, you retrieve a point of reference, which you then use in the subsequent queries to retrieve additional results for the same term before and after the specified point of reference.

Note

By default, Atlas Search sorts the documents in the results by the relevance score of the documents. If multiple documents in the results have identical scores, Atlas Search returns arbitrarily ordered results. To return documents in a determined order, the queries specify a unique field, released, to sort the results.

This section demonstrates how to do the following:

  1. Retrieve Page 1 and Generate Pagination Tokens

  2. Retrieve Page 2 Using searchAfter

  3. Return to Page 1 Using searchBefore

  4. Jump from Page 2 to Page 5 Using searchAfter and $skip

  5. Use Facet with the Paginated Results

Procedure

To run these queries, you must first do the following:

1

Connect to your cluster in mongosh.

Open mongosh in a terminal window and connect to your cluster. For detailed instructions on connecting, see Connect via mongosh.

2

Switch to the sample_mflix database.

use sample_mflix
switched to db sample_mflix
3

Copy, paste, and run the queries.

Retrieve Page 1 and Generate Pagination Tokens

The sample query uses the following pipeline stages to retrieve results for the first page and retrieve tokens or a point of reference for subsequent queries:

  • Searches for titles that contain summer in the title field by using the text operator.

  • Sorts the results by the released field value in ascending order by using the sort option.

Limits the results to 10 documents.

Includes only the title, released, and genres fields from the documents in the results. The query also adds the following fields to each document in the results:

  • paginationToken, which is the token that can be used as a point of reference in subsequent queries

  • score, which is the relevance score of the document in the results

db.movies.aggregate([
  {
    "$search": {
      "index": "pagination-tutorial",
      "text": {
        "path": "title",
        "query": "summer"
      },
      "sort": { "released": 1 }
    }
  },
  {
    "$limit": 10
  },
  {
    "$project": {
      "_id": 0,
      "title": 1,
      "released": 1,
      "genres": 1,
      "paginationToken" : { "$meta" : "searchSequenceToken" },
      "score": { "$meta": "searchScore" }
    }
  }
])

Retrieve Page 2 Using searchAfter

To retrieve additional results, you specify the point of reference after which you want to retrieve the results. This query demonstrates how to retrieve results to build a function like "Next Page" in your application.

The sample query uses the following pipeline stages to retrieve results for the second page using the token generated by searchSequenceToken from the prior query for the same term:

  • Searches for titles that contain summer in the title field by using the text operator.

  • Sorts the results by the released field value in ascending order by using the sort option.

  • Returns documents after the tenth document in the results, which the query specifies by using the pagination token generated by the query you ran to Retrieve Page 1 and Generate Pagination Tokens.

Limits the results to 10 documents.

Includes only the title, released, and genres fields from the documents in the results. It also adds the following fields to each document in the results:

  • paginationToken, which is the token that can be used as point of reference in subsequent queries

  • score, which is the relevance score of the document in the results

db.movies.aggregate([
  {
    "$search": {
      "index": "pagination-tutorial",
      "text": {
        "path": "title",
        "query": "summer"
      },
      "searchAfter": "COwRGgkpAPQV0hQAAAA=",
      "sort": { "released": 1 }
    }
  },
  {
    "$limit": 10
  },
  {
    "$project": {
      "_id": 0,
      "title": 1,
      "released": 1,
      "genres": 1,
      "paginationToken" : { "$meta" : "searchSequenceToken" },
      "score": { "$meta": "searchScore" }
    }
  }
])

Return to Page 1 Using searchBefore

To retrieve previous results, you specify the point of reference before which you want to retrieve the results. This query demonstrates how to retrieve results to build a function like "Previous Page" in your application.

The sample query uses the following pipeline stages to return to results on the first page using the token generated by searchSequenceToken from the prior query for the same term:

  • Searches for titles that contain summer in the title field by using the text operator.

  • Sorts the results by the released field value in ascending order by using the sort option.

  • Returns documents 1 to 10 in the Atlas Search results by using the pagination token associated with the eleventh document in the results of the query you ran to Retrieve Page 2 Using searchAfter.

Limits the results to 10 documents.

Includes only the title, released, and genres fields from the documents in the results. It also adds the following fields to each document in the results:

  • paginationToken, which is the token that can be used as a point of reference in subsequent queries

  • score, which is the relevance score of the document in the results

Note

By default, Atlas Search returns the results in reverse order for queries that specify tokens to retrieve results before a point of reference. To return documents in-order, the query uses the toArray() and the JavaScript reverse() methods.

db.movies.aggregate([
  {
    "$search": {
      "index": "pagination-tutorial",
      "text": {
        "path": "title",
        "query": "summer"
      },
      "searchBefore": "CMwSGgkpAECHcCIAAAA=",
      "sort": { "released": 1 }
    }
  },
  {
    "$limit": 10
  },
  {
    "$project": {
      "_id": 0,
      "title": 1,
      "released": 1,
      "genres": 1,
      "paginationToken" : { "$meta" : "searchSequenceToken" },
      "score": { "$meta": "searchScore" }
    }
  }
]).toArray().reverse()

Jump from Page 2 to Page 5 Using searchAfter and $skip

To skip results and jump from page 2 to 5, you use the token generated by searchSequenceToken to specify the point of reference after which you want to retrieve the results and then skip twenty documents in the results. This query demonstrates how to retrieve results to build a function in your application that allows skipping pages.

The sample query uses the following pipeline stages to jump to results on page 5 by using the token generated by searchSequenceToken from the prior query for the same term and by using the $skip and $limit stages:

  • Searches for titles that contain summer in the title field by using the text operator.

  • Sorts the results by the released field value in ascending order by using the sort option.

  • Returns documents after the twentieth document specified by using the pagination token generated by the query you ran to Retrieve Page 2 Using searchAfter.

Skips 20 documents in the results after the specified point of reference, which is the token associated with the twentieth document in the results for the query you ran to Retrieve Page 2 Using searchAfter.
Limits the results to 10 documents.

Includes only the title, released, and genres fields from the documents in the results. It also adds the following fields to each document in the results:

  • paginationToken, which is the token that can be used as a point of reference in subsequent queries

  • score, which is the relevance score of the document in the results

db.movies.aggregate([
    {
      "$search": {
        "index": "pagination-tutorial",
        "text": {
          "path": "title",
          "query": "summer"
        },
        "searchAfter": "COwRGgkpAPQV0hQAAAA=",
        "sort": { "released": 1 }
      }
    },
    {
      "$skip": 20
    },
    {
      "$limit": 10
    },
    {
      "$project": {
        "_id": 0,
        "title": 1,
        "released": 1,
        "genres": 1,
        "paginationToken" : { "$meta" : "searchSequenceToken" },
        "score": { "$meta": "searchScore" }
      }
    }
])

Use Facet with the Paginated Results

This section demonstrates how searchSequenceToken can be used with Atlas Search facets.

The sample query uses the following pipeline stages:

  • Searches for titles that contain summer in the title field by using the facet collector.

  • Retrieves a count of the number of total movies in the results in each genre by using facets option.

Adds the paginationToken field to store the tokens for each document in the results generated by using the searchSequenceToken option.
Limits the results to 10 documents.

Returns the following fields:

  • docs field, which contains only the title, released, and genres fields from the documents in the results and the paginationToken field.

  • meta field, which contains a count of the total number of movies in the results in each genre that is stored in the $$SEARCH_META variable.

db.movies.aggregate([
    {
      "$search": {
        "index": "pagination-tutorial",
        "facet": {
          "operator": {
            "text": {
              "path": "title",
              "query": "summer"
            } 
          },
          "facets": {
            "genresFacet": {
              "type": "string",
              "path": "genres"
            }
          }
        }
      }
    },
    { 
      "$addFields": {
        "paginationToken" : { "$meta" : "searchSequenceToken" }
      }
    },
    { "$limit": 10 },
    {
      "$facet": {
        "docs": [
          { "$project":
            {
              "_id": 0,
              "title": 1,
              "released": 1,
              "genres": 1,
              "paginationToken" : 1
            }
          }
        ],
        "meta": [
          { "$replaceWith": "$$SEARCH_META" },
          { "$limit": 1 }
        ]
      }
    },
    {
      "$set": {
        "meta": {
          "$arrayElemAt": ["$meta", 0]
        }
      }
    }
])

Back

Paginate Results

Next

All Results

On this page