Paginators allow you to consume potentially-long streams of data - like lists of posts for Mastodon, or messages in a channel for Discord - in a sustainable and transparent manner. Essentially, Piecewise allows you to loop through the structure easily, while obtaining more data (pages) behind-the-scenes. Paginators are marked by the paper 📄 emoji in Piecewise.
There are a few things to keep in mind when using paginators:
- Paginators are designed to loop through long streams of data. By design, they are inherently expensive and incredibly slow, and should be used in cases where collecting large amounts of data is necessary.
- Piecewise, in most cases, will attempt to automatically throttle requests made via your paginator. However, Piecewise does not monitor all paginator requests, so avoid multiple paginator requests to a single resource at the same time to reduce the possibility of exceeding rate limits.
- Paginators will continue to run until there is no data left. In many cases, this may be the first post a user made, the first post in a channel, etc. Use the “break” block when you have obtained the data you require, if you do not intend to request all data from a paginator.