Pagination

Cursors

All ElectroDB query and scan operations return a cursor, which is a stringified and copy of DynamoDB’s LastEvaluatedKey with a base64url encoding.

The terminal method go() accepts a cursor when executing a query or scan to continue paginating for more results. Pass the cursor from the previous query to your next query and ElectroDB will continue its pagination where it left off.

To limit the number of items ElectroDB will retrieve, read more about the Query Options pages and limit.

Entities

The Entity and Table Definition tabs show the setup this example runs against. The first query runs without a cursor; the second passes the cursor returned by the first to continue paginating.

import { StoreLocations } from "./entity";

const results1 = await StoreLocations.query
  .leases({ storeId: "LatteLarrys" })
  .go(); // no "cursor" passed to `.go()`

const results2 = await StoreLocations.query
  .leases({ storeId: "LatteLarrys" })
  .go({ cursor: results1.cursor }); // Paginate by querying with the "cursor" from your first query

Services

Pagination with services is also possible. Similar to Entity Pagination, calling the .go() method returns the following structure:

type GoResults = {
  cursor: string | null;
  data: {
    [entityName: string]: {
      /** EntityItem */
    }[];
  };
};

Execution Options

Count

The execution option count allows you to specify a specific number of items to be returned. This is often a difficult task with DynamoDB because queries do not always return a consistent number of items. If your query includes filters, and requires pagination, it can be even harder to return a specific number of items reliably. When using count, ElectroDB will paginate your query against DynamoDB until the number of items matches the supplied count, create a custom cursor, and return the items found. This option is recommend for queries with numerous and/or strict attribute filters where end-user or external pagination is necessary.

The Entity and Table Definition tabs show the setup this example runs against.

import { StoreLocations } from "./entity";

type GetLeasesOptions = {
  storeId: string;
  cursor?: string | null;
  limit: number;
};

async function getLeases(options: GetLeasesOptions) {
  const { storeId, cursor, limit } = options;

  if (limit < 1 || limit >= 200) {
    throw new Error("Limit must be at least 1 and at most 200");
  }

  return StoreLocations.query.leases({ storeId }).go({ cursor, count: limit });
}

await getLeases({ storeId: "LatteLarrys", cursor: null, limit: 10 });

Pages

The execution option pages allows you to automatically perform multiple queries against DynamoDB. By default, ElectroDB queries will perform one request against DynamoDB. With pages, you can specify the number of queries you’d like to occur under the hood before returning. Furthermore, if you would like ElectroDB to return all results for a given query (i.e., exhausting pagination for a given query automatically) you can use the option {pages: "all"}. Note that while option is convenient, it may not performant for some workflows.

Example

Simple pagination example:

The Entity and Table Definition tabs show the setup this example runs against. Because the mocked query always returns an empty page, this loop exits after a single iteration below — against a real table it continues until cursor is null.

// EntityItem is the type for a returned item
// QueryResponse is the type for the full electrodb response to a query
import type { EntityItem, QueryResponse } from "electrodb";

// (your entity)
import { users } from "./entity";

type UserItem = EntityItem<typeof users>;
type UserQueryResponse = QueryResponse<typeof users>;

async function getTeamMembers(team: string) {
  let members: UserItem[] = [];
  let cursor = null;
  do {
    const results: UserQueryResponse = await users.query
      .members({ team })
      .go({ cursor });
    members = [...members, ...results.data];
    cursor = results.cursor;
  } while (cursor !== null);

  return members;
}

await getTeamMembers("engineering");