mirror of
https://github.com/ash-project/ash.git
synced 2024-09-21 22:13:02 +12:00
138 lines
5.6 KiB
Markdown
138 lines
5.6 KiB
Markdown
# Pagination
|
|
|
|
Pagination when reading records is configured on a per-action basis. Ash supports two kinds of pagination: `keyset` and `offset`.
|
|
|
|
A single action can use both kinds of pagination if desired, but typically you would use one or the other.
|
|
|
|
For information on configuring actions to support pagination, see `d:Ash.Resource.Dsl.actions.read|prepare`.
|
|
|
|
> #### Counting records {: .tip}
|
|
>
|
|
> When calling an action that uses pagination, the full count of records can be requested by adding the option `page: [count: true]`.
|
|
> Note that this will perform a similar query a second time to fetch the count, which can be expensive on large data sets.
|
|
|
|
## Offset Pagination
|
|
|
|
Offset pagination is done via providing a `limit` and an `offset` when making queries.
|
|
|
|
* The `limit` determines how many records should be returned in the query.
|
|
* The `offset` describes how many records from the beginning should be skipped.
|
|
|
|
Using this, you might make requests like the following:
|
|
|
|
```elixir
|
|
# Get the first ten records
|
|
Api.read(Resource, page: [limit: 10])
|
|
# or by using an action named `read` directly
|
|
Resource.read(page: [limit: 10])
|
|
|
|
# Get the next ten records
|
|
Api.read(Resource, page: [limit: 10, offset: 10])
|
|
# or by using an action named `read` directly
|
|
Resource.read(page: [limit: 10, offset: 10])
|
|
```
|
|
|
|
Next/previous page requests can also be made in memory, using an existing page of search results:
|
|
|
|
```elixir
|
|
# Return page three of search results
|
|
{:ok, third_page} = Resource.read(page: [limit: 10, offset: 20])
|
|
|
|
# Use `:prev` and `:next` to go backwards and forwards.
|
|
# `:first`, `:last`, `:self` and specifying a page number are also supported.
|
|
{:ok, second_page} = Api.page(third_page, :prev)
|
|
{:ok, fourth_page} = Api.page(third_page, :next)
|
|
```
|
|
|
|
### Pros of offset pagination
|
|
|
|
- Simple to think about
|
|
- Possible to skip to a page by number. E.g the 5th page of 10 records is `offset: 40`
|
|
- Easy to reason about what page you are currently on (if the total number of records is requested)
|
|
- Can go to the last page (though data may have changed between calculating the last page details, and requesting it)
|
|
|
|
### Cons of offset pagination
|
|
|
|
- Does not perform well on large datasets (if you have to ask if your dataset is "large", it probably isn't)
|
|
- When moving between pages, if data was created or deleted, individual records may be missing or appear on multiple pages
|
|
|
|
## Keyset Pagination
|
|
|
|
Keyset pagination is done via providing an `after` or `before` option, as well as a `limit`.
|
|
|
|
* The `limit` determines how many records should be returned in the query.
|
|
* The `after` or `before` value should be a `keyset` value that has been returned from a previous request. Keyset values are returned whenever there is any read action on a resource that supports keyset pagination, and they are stored in the `__metadata__` key of each record.
|
|
|
|
|
|
> #### Keysets are directly tied to the sorting applied to the query {: .warning}
|
|
>
|
|
> You can't change the sort applied to a request being paginated, and use the same keyset. If you want to change the sort, but *keep* the record who's keyset you are using in the `before` or `after` option, you must first request the individual record, with the new sort applied. Then, you can use the new keyset.
|
|
|
|
|
|
For example:
|
|
|
|
```elixir
|
|
{:ok, page} = Api.read(Resource, page: [limit: 10])
|
|
# Returns `{:ok, %Ash.Page.Keyset{results: [...], before: nil, after: nil}}`
|
|
# The `before`/`after` values are the keysets used for this request.
|
|
|
|
# Fetch the keyset for the next request from the results list
|
|
last_record = List.last(page.results)
|
|
# Returns `%Resource{__metadata__: %{keyset: "g2wAAAABbQAAACQzOWNjNTcwNy00NjlmL..."}, ...}``
|
|
|
|
# Use this keyset value to fetch the next page
|
|
{:ok, next_page} = Api.read(Resource, page: [limit: 10, after: last_record.__metadata__.keyset])
|
|
```
|
|
|
|
Like offset pagination, next/previous page requests can also be made in memory, using an existing page of search results:
|
|
|
|
```elixir
|
|
# Return page three of search results
|
|
{:ok, third_page} = Resource.read(page: [limit: 10])
|
|
|
|
# Use `:prev` and `:next` to go backwards and forwards.
|
|
# `:first` and `:self` can also be used, but `:last` and specifying a page number are not supported.
|
|
{:ok, second_page} = Api.page(third_page, :prev)
|
|
{:ok, fourth_page} = Api.page(third_page, :next)
|
|
```
|
|
|
|
### Pros of keyset pagination
|
|
|
|
- Performs very well on large datasets (assuming indices exist on the columns being sorted on)
|
|
- Behaves well as data changes. The record specified will always be the first or last item in the page
|
|
|
|
### Cons of keyset paginations
|
|
|
|
- A bit more complex to use
|
|
- Can't go to a specific page number
|
|
|
|
## Example implementation
|
|
|
|
### Setting up the resource
|
|
|
|
Add the `pagination` macro call to the [action](glossary.md#action) of the [resource](glossary.md#resource) that you want to be paginated.
|
|
|
|
```elixir
|
|
defmodule AppName.ResourceName do
|
|
use Ash.Resource
|
|
|
|
actions do
|
|
read :read_action_name do
|
|
pagination offset?: true, default_limit: 3, countable: true
|
|
end
|
|
|
|
# ...
|
|
```
|
|
|
|
For all available pagination options, see `d:Ash.Resource.Dsl.actions.read|pagination`.
|
|
|
|
### Querying the paginated resource
|
|
|
|
For all available querying options, see [`Ash.Api.read.pagination`](https://hexdocs.pm/ash/Ash.Api.html#c:read/2-pagination).
|
|
|
|
> #### Check the updated query return type! {: .info}
|
|
> Pagination will modify the return type of calling the query action.
|
|
>
|
|
> Without pagination, Ash will return a list of records.
|
|
>
|
|
> But _with_ pagination, Ash will return an `Ash.Page.Offset` struct (for offset pagination) or `Ash.Page.Keyset` struct (for keyset pagination). Both structs contain the list of records in the `results` key of the struct.
|