System Pagination Tokens (Paged Data Grids) – Documentation and Support | Knowi

When a Data Grid visualization is set to Paged navigation mode (widget Settings → Pagination → Navigation Mode), Knowi resolves the following system tokens in Direct queries each time a page is requested. Use them to push pagination down to your datasource, so that each page click fetches only that page of data:

$c9syspage_number$ - the requested page number, starting at 1.
$c9syspage_size$ - the configured Rows Per Page of the widget.
$c9sysoffset$ - the precomputed row offset: (page number - 1) x page size.

Unlike user-defined runtime parameters, these tokens are supplied automatically by the widget on each page request - they are not driven by dashboard filters.

SQL example:

select order_id, customer, total
from orders
order by order_id
limit $c9_sys_page_size$ offset $c9_sys_offset$

REST API examples (URL parameters):

/v1/getInventoryDetails?accountId=277152&pageSize=$c9_sys_page_size$&page=$c9_sys_page_number$

/v1/events?accountId=277152&limit=$c9_sys_page_size$&offset=$c9_sys_offset$

Map the tokens to whatever your endpoint expects (page, offset, limit, pageSize, start, etc.). Use $c9_sys_page_number$ for APIs that expect a page index and $c9_sys_offset$ for APIs that expect a row offset/skip/start value. For REST APIs, the tokens can be used in the endpoint URL, POST body, URL parameters, or Cloud9QL transformation.

Returning an exact total (optional):

To show exact page numbers and a total row count in the pager, return the pre-pagination row count in a column aliased $c9_sys_total$ . For example, in SQL:

select order_id, customer, total, count(*) over() as "$c9_sys_total$"
from orders
order by order_id
limit $c9_sys_page_size$ offset $c9_sys_offset$

The $c9_sys_total$ column is treated as metadata: it is stripped from the results before display and never appears in the grid or the dataset. It must contain the total row count before pagination, not the total number of pages. If a REST API returns only a page count, do not map that value directly to $c9_sys_total$ ; leave the total unset unless the API can return a row count. If no total is provided (and Compute Total Pages cannot determine one), the pager shows Previous/Next controls and assumes more pages exist whenever a full page is returned.

Notes:

In the query editor Preview and on the initial dashboard load, the tokens resolve to page 1 values.
Knowi-hosted datasets and Direct MongoDB queries do not require these tokens - pagination and totals are applied automatically.
In Paged Data Grid mode, column header sorting is sent to the backend with the requested sort field and direction. Knowi-hosted datasets and Direct MongoDB queries apply that sort before the page slice. Direct SQL and REST API queries that use page-advancing tokens must apply the matching ORDER BY or API sort parameter at the datasource/API level for the full dataset to remain sorted across pages; a post-fetch Cloud9QL order by can only sort the current page.

Related articles