Server-Driven Paging in OData Web Services

Paging ensures that the quantity of data that is returned by an OData URI doesn't overwhelm Business Central Server or client program that you use to capture data, while optimizing performance.

Overview

The size of data in results of an OData request will affect performance. In general, the more data you have, the longer it takes to process the request, potentially increasing memory usage. With pages that are slow, this condition can lead to request timeouts and out-of-memory exceptions.

Paging divides the data feed of a request into smaller chunks, or pages, which can't contain more than a specific number of entities. In essence, each page is handled as a separate request, with its own timeout. Business Central on-premises and online are set up to use a maximum of 20,000 entities per page by default. With Business Central on-premises, page size is determined by a configuration setting on the Business Central Server, which you can change. With Business Central online, the page size is configured on the service and can't be changed.

However, with both on-premises and online, you can override the server-drive paging on a request-basis. This capability allows you to handle situations where you're experiencing timeouts and memory exceptions.

Configuring server-driven paging for on-premises

You configure server-driven paging with the Max Page Size setting in the configuration for the Business Central Server instance that you're using for OData services. To modify the setting, you can use Server Administration Tool or Business Central Windows PowerShell Cmdlets. For more information about Max Page Size and other Business Central Server parameters, see Configuring Business Central Server.

An increase in the Max Page Size will increase the memory consumption on the Business Central Server or client. If the value is too large, it can overload the memory on Business Central Server. For performance reasons, you should try to set the value of the Max Page Size as large as possible without overloading Business Central Server.

When using OData with queries that are set with a top number of rows by either the TopNumberOfRows Property and TopNumberOfRows Method, you should set the Max Page Size value greater than the value of the TopNumberOfRows property and TopNumberOfRows method. For more information, see Using OData with Queries That are Set with a Top Number of Rows.

Overriding Server-Driven Paging

Instead relying on the server-driven paging setting, you can set paging on individual requests by the client. Setting paging on requests is useful when pages are slow and you're experiencing timeouts or out of memory exceptions.

To set paging on a request, use the odata.maxpagesize preference in the Prefer header of the HTTP request:

Prefer: odata.maxpagesize=300

See Also

OData Web Services