Lesson 8

Code Page Here - PeoplePage_pagination.html

Query Metadata and Pagination

Control how many records Quickbase returns, decide how many records should be skipped, inspect the JSON request, and watch the response metadata change with every query.

Lesson Objective

Request Controlled Portions of a Quickbase Result Set

Instead of asking Quickbase to return every matching record at once, use top and skip to request a specific portion of the result set.

The Important Change

Pagination Happens in the Quickbase Request

Lesson 2 manipulated records after they had already reached JavaScript. Lesson 8 does something fundamentally different.

Client-Side Manipulation

Quickbase
    ↓
All returned records
    ↓
JavaScript
    ↓
Manipulate locally

Quickbase Pagination

JavaScript
    ↓
top / skip
    ↓
Quickbase REST API
    ↓
Only requested portion
    ↓
JavaScript

Two Pagination Controls

Understanding top and skip

top

The maximum number of records Quickbase should return in this request.

top: 2

"Return no more than
2 records."

skip

The number of matching records Quickbase should move past before returning data.

skip: 2

"Move past the first
2 records."

Lesson 8 Roadmap

Five Steps Through a Paginated REST Query

First understand the two values. Then change them yourself and watch the request, metadata, and returned records respond together.

Choose top and skip

Decide how many records Quickbase may return and where the returned portion should begin.

Build the JSON request

Place those values inside the REST query options object.

Send the query

Quickbase receives the pagination instructions as part of POST /v1/records/query.

Inspect response metadata

Compare totalRecords, numRecords, top, and skip.

Inspect the returned records

See exactly which People records belong to that portion of the result set.

Choose top and skip

The working Code Page changed loadPeople() so the pagination values could be supplied instead of being permanently hardcoded.

async function loadPeople(
  top = 2,
  skip = 0,
) {
  ...
}

That means these two calls request different portions of the same result set:

loadPeople(2, 0);
// return up to 2 records,
// skipping none

loadPeople(2, 2);
// skip the first 2,
// then return up to 2

Interactive REST Pagination Lab

Simulate the Quickbase Request

This training instrument uses local template People records. No Quickbase API call is made from this tutorial page. The controls simulate the same top, skip, response metadata, and returned-record behavior used by the working Code Page.

Records to return (top)

Records to skip (skip)

Try a prepared experiment

Simulated API Call #1

The simulated request asked Quickbase to skip 0 record(s) and return a maximum of 2.

JSON Request Sent to Quickbase

{
  "from": "PEOPLE_TABLE_DBID",
  "select": [
    3,
    6,
    7,
    8
  ],
  "options": {
    "top": 2,
    "skip": 0
  },
  "sortBy": [
    {
      "fieldId": 6,
      "order": "ASC"
    }
  ]
}

Simulated Quickbase Response Metadata

Total Records

Records Returned

Top

Skip

What just happened?

There are 10 total matching records. Quickbase skipped 0 and was allowed to return no more than 2.

The response contains 2 record(s).

This portion begins with Alice and ends with Anne.

Records Returned by the Simulated API

Record ID	Name	Age	Favorite Color
1	Alice	23	Blue
12	Anne	42	White

Put Pagination Inside the JSON Request

In the working Quickbase Code Page, top and skip belong inside the query's options object.

const query = {
  from: TABLE_DBID,

  select: [
    FIELD_IDS.recordId,
    FIELD_IDS.name,
    FIELD_IDS.age,
    FIELD_IDS.favoriteColor,
  ],

  options: {
    top,
    skip,
  },

  sortBy: [
    {
      fieldId: FIELD_IDS.name,
      order: "ASC",
    },
  ],
};

Aha Moment

top Does Not Mean “Return Exactly This Many”

It specifies the maximum number requested. Quickbase cannot return records that do not remain in the result set.

totalRecords = 10
skip         = 8
top          = 4

10 total
- 8 skipped
-----------
  2 remain

numRecords = 2

That distinction between top and numRecords is exactly why the response metadata matters.

Send a New REST Query Each Time

The Run button reads the current control values and calls loadPeople()again with those values.

function runPaginationQuery() {
  const top = Number(
    document.getElementById(
      "topInput",
    ).value,
  );

  const skip = Number(
    document.getElementById(
      "skipInput",
    ).value,
  );

  loadPeople(
    top,
    skip,
  );
}

This is not JavaScript pagination.

The controls determine the values sent in a new Quickbase REST request. Quickbase returns the requested portion.

Read Quickbase's Pagination Metadata

The response metadata describes both the complete matching set and the particular portion returned by the request.

const metadata =
  parsed.metadata;

metadata.totalRecords;
metadata.numRecords;
metadata.top;
metadata.skip;

Metadata	Meaning
`totalRecords`	Total records belonging to the complete query result.
`numRecords`	Number of records actually returned in this response.
`top`	Maximum number requested.
`skip`	Number of records moved past before results began.

Use skip to Move Through the Result Set

With a page size of two, moving through the records means increasing skip by two each time.

Request	top	skip	Portion Requested
First	2	0	Records 1–2
Second	2	2	Records 3–4
Third	2	4	Records 5–6

Complete Pagination Flow

INPUT → JSON → QUICKBASE → METADATA → RECORDS

Choose top and skip
      ↓
Run Quickbase Query
      ↓
loadPeople(top, skip)
      ↓
Build options
{
  top,
  skip
}
      ↓
POST /v1/records/query
      ↓
Quickbase processes pagination
      ↓
JSON response
      ↓
metadata
├── totalRecords
├── numRecords
├── top
└── skip
      ↓
data[]
      ↓
Render only returned records

Why We Did Not Start with Previous / Next

Buttons Would Hide the Interesting Part

Once the learner understands top, skip, and response metadata, Previous and Next buttons become straightforward.

NEXT

skip = skip + top


PREVIOUS

skip = skip - top

The user interface is merely automating values we now understand.

Lesson 8 Complete

You Can Now Control How Much Data Quickbase Returns

You used top and skip to define a portion of a result set, inspected the JSON request, interpreted Quickbase response metadata, and observed how the returned records change as the pagination values change.

Next: Lesson 9 — Relationships

We now know how to read, query, create, update, delete, and paginate records. The next lesson moves beyond a single table and begins exploring how Quickbase tables relate to one another.