Headless Server Developer Manual / 4.12 Pagination

Headless Server Developer Manual / Version 2204

4.12 Pagination

Overview

To optimize communication between client and server and to reduce overfetching, data can be retrieved paginated from the Headless Server.

There are two possibilities to retrieve paged data in the Headless Server:

Retrieve data completely from the data sources, paging is applied afterwards.
Retrieve only a subset of data, pagination is applied to data sources.

The Headless Server exposes both possibilities in the same way to the client. The different paging mechanisms are applied in the GraphQL schema.

Fields that can be retrieved paged are suffixed with "Paged", e.g. items and itemsPaged. The optional parameters are offset and limit and the return value is a *PaginationResult depending on the result type of the collection.

A paged field is defined with the following pattern:

fieldPaged(offset: Int, limit: Int): *PaginationResult

A pagination result type is defined with a specific list, for example Content_:

type ContentPaginationResult {
  totalCount: Double
  result: [Content_]
}

Apply paging after data retrieval

Not all data source accesses allow a paged query. For example, a content has a list property. This list property is always retrieved completely together with all other content properties from the Content Server, it cannot be loaded partially. The Headless Server provides the possibility to apply paging, after the data was retrieved by invoking a pagingHelper. The pagingHelper gets the offset, limit and the original collection as parameters and returns a paged result.

Example how to apply the pagingHelper to a list property:

itemsPaged(offset: Int, limit: Int): CollectionItemPaginationResult @fetch(from: "@pagingHelper.apply(#offset, #limit, #this.items)")

Apply paging in Adapter

If data should be retrieved paged from a data source, the corresponding Adapter can implement the PagingAware interface. This interface provides methods to apply offset and limit and to return a Paging result containing metadata and the actual result.

Example how to get a paged result from a PagingAware Adapter:

itemsPaged(offset: Int, limit: Int): CollectionItemPaginationResult @fetch(from: "@queryListAdapter.to(#root).getPagingResult(#offset, #limit)")

Return types

Paged fields return a *PaginationResult type, that contains metadata and the result. For each result type, either a specific *PaginationResult type needs to be defined or the generic ContentPaginationResult type can be used. See content-schema.graphql for predefined *PaginationResult types.

A paged result looks like:

"itemsPaged": {
          "totalCount": 4,
          "result": [
            {
              "id": "7326"
            },
            {
              "id": "7334"
            }
          ]
        }

Add a custom paged field

To add a custom paged field, first it needs to be decided, if the paging should be applied on data retrieval (PagingAware Adapter) or after data retrieval (pagingHelper).

PagingAware Adapter:

Let the custom Adapter implement the interface PagingAware and implement the corresponding functions.
Add a new field to the schema with parameters offset and limit and a fetch directive that calls the Adapter's getPagingResult method.

PagingHelper:

Add a new field to the schema with parameters offset and limit and a fetch directive that calls the pagingHelper with offset, limit and the original list (e.g. #this.items).

The return type definition applies to both variants:

If a custom return type is required, define a new *PaginationResult return type with fields totalResult and result. Define a custom type for the result field.
Alternatively use one of the predefined *PaginationResult return types.

Search Results

Table Of Contents

Filter