Pagination

A find never dumps an entire collection on you. It returns one page of documents plus the numbers you need to fetch the next one. That's why find hands back an object with a docs array rather than the array itself — the wrapper carries the page's documents and its pagination metadata.

The paginated result

Every list read resolves to this shape:

const result = await client.collection('posts').find()

result.docs         // the documents on this page
result.total        // total documents matching the query, across all pages
result.limit        // documents per page
result.page         // the current page number (1-indexed)
result.totalPages   // how many pages exist at this limit
result.hasNextPage  // is there a page after this one?
result.hasPrevPage  // is there a page before this one?

So to render the documents you reach for result.docs; to build page controls you use total, totalPages, and the two boolean flags.

Choosing the page and its size

Two options steer pagination. The limit option sets how many documents a page holds (default 10, with a maximum allowed value of 100). The page option picks which page to return (default 1):

// The second page, 20 posts per page
const result = await client.collection('posts').find({ limit: 20, page: 2 })

The same options exist on the chained builder:

await client.collection('posts').find().limit(20).page(2)

Walking through every page

Because hasNextPage tells you when to stop, looping through a whole collection is a small while:

let page = 1
const all = []

while (true) {
  const result = await client.collection('posts').find({ limit: 100, page })
  all.push(...result.docs)
  if (!result.hasNextPage) break
  page++
}

Dyrected always paginates list reads, so this loop — rather than a single unbounded request — is the way to pull an entire collection. A larger limit means fewer round-trips; keep in mind that the limit parameter has a hard cap of 100 to keep responses fast and reliable. Note that this cap applies only to list pagination page sizes; other operations, such as generating mock data via seeding, are not restricted by this limit.

Fetching a single expected match

When you're querying by something unique — a slug, an email — and expect exactly one document, set limit: 1 and read the first element. It keeps the response small and the intent clear:

const result = await client.collection('posts').find({
  where: { slug: { equals: 'hello-world' } },
  limit: 1,
})
const post = result.docs[0]

If you already have the document's ID, skip pagination entirely and use findOne, which returns a single document directly instead of a page.

Pagination sits at the end of the query pipeline: filter chooses the documents, sort orders them, and limit/page decide how many of that ordered set you receive at a time.