Tutorial 2 - Pagination

turning the page! in tutorial 2, we'll control how many items graph returns on each page of results and retrieve specific pages prerequisites you have completed the first learning graphql tutorial about graphql optional read more about graphql and when it might be best used introduction when graphql returns results, it will organise them into pages this allows it to be more efficient, as it only returns the data that is needed straight away at the same time, the rest of the pages are organised ready for the next request you'll always need to think about pagination when using graphql, even you only want to retrieve the first page of results per page per page is an argument used to define the number of results that will be returned on each page it's now a mandatory argument on some types of query so we've already got the argument in our query from the last tutorial query get all records { records( per page 20 ) { total entries results { model schema name properties } } } experiment by changing the integer in the argument from 20 to another value, e g 1 observe the difference it's recommended to keep the per page number as low as possible for efficiency and performance let's consider a few situations you want to display 3 items set per page to 3 only the three items you need will be retrieved you want to display 20 items at a time, but allow the user to view the next 20 when they've finished reading set per page to 20 if you want the user to be able to change per page dynamically, we'll cover this when we look at variables in a future tutorial if you think you need to display more than 2000 items at a time (perhaps to provide data to a javascript plugin), consider using get requests to a custom liquid endpoint page to fetch each page of results asynchronously you can learn more in tutorial 8 building a liquid api get endpoint page powered by graphql queries docid\ xve0gn5jfaau9xo9fh5rv but we recommend working through the other tutorials first returning pagination metadata you can return pagination metadata alongside your query results current page returns the number of the current page per page returns the number of items on every page has previous page a boolean which is true if there is a page before the current page has next page a boolean which is true if there is a page after the current page total pages returns an integer representing the total number of pages in these results these optional properties can be requested alongside total entries and your results object, like in the example below try them out code query get all records { records( per page 20 ) { current page total pages has previous page has next page per page total entries results { model schema name properties } } } notes properties like has next page and has previous page are most useful for adding pagination buttons of your own you can see that by default, we get the first page of results so page returns 1 explorer changing the page you can view other pages by setting the page argument to the page of results you'd like to see code query get all records { records( page 2 per page 20 ) { current page total pages results { model schema name properties } } } explorer next time in the next article, we'll look at how to filter results for example, we'll learn how to return items from only a specific webapp let's go!