View Source Read Actions

Read actions operate on an Ash.Query. Read actions always return lists of data. The act of pagination, or returning a single result, is handled as part of the interface, and is not a concern of the action itself. Here is an example of a read action:

# Giving your actions informative names is always a good idea
read :ticket_queue do
  # Use arguments to take in values you need to run your read action.
  argument :priorities, {:array, :atom} do
    constraints items: [one_of: [:low, :medium, :high]]
  end

  # This action may be paginated,
  # and returns a total count of records by default
  pagination offset: true, countable: :by_default

  # Arguments can be used in preparations and filters
  filter expr(status == :open and priority in ^arg(:priorities))
end

Ash.get!

The Ash.get! function is a convenience function for running a read action, filtering by a unique identifier, and expecting only a single result. It is equivalent to the following code:

Ash.get!(Resource, 1)

# is roughly equivalent to

Resource
|> Ash.Query.filter(id == 1)
|> Ash.Query.limit(2)
|> Ash.read!()
|> case do
  [] -> # raise not found error
  [result] -> result
  [_, _] -> # raise too many results error
end

Ash.read_one!

The Ash.read_one! function is a similar convenience function to Ash.get!, but it does not take a unique identifier. It is useful when you expect an action to return only a single result, and want to enforce that and return a single result.

Ash.read_one!(query)

# is roughly equivalent to

query
|> Ash.Query.limit(2)
|> Ash.read!()
|> case do
  [] -> nil
  [result] -> result
  [_, _] -> # raise too many results error
end

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 pagination configuration reference, see Ash.Resource.Dsl.actions.read.pagination.

Counting records

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:

# Get the first ten records
Ash.read(Resource, page: [limit: 10])
# or by using an action named `read` directly through a
# code interface on the domain
Domain.read(page: [limit: 10])

# Get the next ten records
Ash.read(Resource, page: [limit: 10, offset: 10])
# or by using an action named `read` directly through a
# code interface on the domain
Domain.read(page: [limit: 10, offset: 10])

Next/previous page requests can also be made in memory, using an existing page of search results:

# 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} = Ash.page(third_page, :prev)
{:ok, fourth_page} = Ash.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

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:

{:ok, page} = Ash.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} = Ash.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:

# 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} = Ash.page(third_page, :prev)
{:ok, fourth_page} = Ash.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 of the resource that you want to be paginated.

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 Ash.Resource.Dsl.actions.read.pagination.

Check the updated query return type!

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.

What happens when you call Ash.Query.for_read/4

The following steps are performed when you call Ash.Query.for_read/4.

What happens when you run the action

These steps are trimmed down, and are aimed at helping users understand the general flow. Some steps are omitted.

  • Run Ash.Query.for_read/3 if it has not already been run
  • Apply tenant filters for attribute
  • Apply pagination options
  • Run before action hooks
  • Multi-datalayer filter is synthesized. We run queries in other data layers to fetch ids and translate related filters to (destination_field in ^ids)
  • Strict Check & Filter Authorization is run
  • Data layer query is built and validated
  • Field policies are added to the query
  • Data layer query is Run
  • Authorizer "runtime" checks are run (you likely do not have any of these)

The following steps happen while(asynchronously) or after the main data layer query has been run

  • If paginating and count was requested, the count is determined at the same time as the query is run.
  • Any calculations & aggregates that were able to be run outside of the main query are run
  • Relationships, calculations, and aggregates are loaded