read

read

A read action on a store resource. Defines how records are queried, including arguments, filters, sorting, and pagination. Read actions support both list queries (returning multiple records) and singular lookups (returning one record). Compiles to an Ash Framework read action at runtime.

When to use

Use read when you need to:

• Query records by specific criteria (e.g., “all orders with status pending”)
• Look up a single record by a unique field (e.g., “find user by email”)
• Define reusable named queries that steps can call
• Sort and paginate results
• Execute raw SQL against external databases

Use defaults: [read] for a standard read action that returns all records, or define named read actions with filters for specific query patterns.

Syntax

resource <resource_name>
  read <action_name>
    argument <name> as <type>, <modifiers>
    filter: <expression>
    sort: <field>, <direction>
    get: true
    prepare <function>

Raw SQL (external databases only)

resource <resource_name>
  read <action_name>
    sql: "<SQL query>"
    params: [arg(<name>)]

Parameters

Parameter	Required	Description
action_name	Yes	Bare identifier naming this action. Multiple read actions can exist on a single resource.
argument	No	Named parameter for the query. Callers pass argument values when invoking the action. Can appear multiple times.
filter	No	Expression that filters results. Use arg(<name>) to reference argument values.
sort	No	Field to sort by. Add desc for descending order. Default is ascending.
get	No	When true, the action returns a single record instead of a list. Returns an error if no record matches.
prepare	No	Preparation function that modifies the query before execution.
sql	No	Raw SQL query string. For external databases where the Ash query DSL is insufficient.
params	No	SQL parameter bindings. Used with sql to pass argument values safely.

Argument modifiers

Modifier	Description	Example
is required	Argument must be provided by the caller	argument email as text, is required
default: <value>	Default value if not provided	argument limit as number, default: 25

Filter expressions

Filters use the mashin expression language. Reference arguments with arg(<name>) and fields by their bare names.

Operator	Description	Example
==	Equality	filter: status == "active"
!=	Inequality	filter: role != "guest"
>, <, >=, <=	Comparison	filter: age >= arg(min_age)
and	Logical AND	filter: active == true and role == arg(role)
or	Logical OR	filter: status == "pending" or status == "review"
in	Membership	filter: category in arg(categories)

Examples

Filtered query with arguments

resource product
  id as uuid, is primary_key
  name as text, is required
  category as text
  price as decimal
  in_stock as boolean, default: true
  timestamps

  read by_category
    argument category as text, is required
    argument max_price as decimal
    filter: category == arg(category) and price <= arg(max_price)
    sort: price

  read in_stock
    filter: in_stock == true
    sort: name

Singular lookup

resource user
  id as uuid, is primary_key
  email as text, is required
  timestamps

  read by_email
    argument email as text, is required
    filter: email == arg(email)
    get: true

When get: true is set, the action returns a single record or an error if none is found. This is useful for lookups by unique fields.

Raw SQL on an external database

resource report, table: "monthly_reports"
  id as uuid, is primary_key
  month as text
  revenue as decimal
  costs as decimal

  read quarterly_summary
    argument quarter as integer, is required
    sql: "SELECT month, SUM(revenue) as revenue, SUM(costs) as costs FROM monthly_reports WHERE EXTRACT(QUARTER FROM to_date(month, 'YYYY-MM')) = $1 GROUP BY month"
    params: [arg(quarter)]

Governance

Read actions are governed effects. When a machine executes a read action:

1. The governance interpreter checks the db capability
2. The action is subject to any policy blocks on the resource (e.g., row-level filtering based on actor attributes)
3. The query and its results are recorded in the behavioral ledger
4. Policies can restrict which records are visible to which actors

Read actions are typically lower risk than write actions, but governance still applies. Sensitive data queries (e.g., reading PII) should have explicit policies.

Translations

Language	Keyword
English	read
Spanish	leer
French	lire
German	lesen
Japanese	読取
Chinese	读取
Korean	읽기

See also

• resource - Resource declarations
• create - Create actions for inserting data
• update - Update actions for modifying records
• destroy - Destroy actions for deleting records
• policy - Authorization policies on actions
• Expression language - Filter expression syntax