What a rule may read

Copy Markdown View Source

A rule runs on the client, so it can only read what the client holds. It is checked and compiled when the resource compiles. If it reads something a client cannot read, or uses a function the client cannot run, compilation fails with a message that names the action.

What you can read

In the expressionReadsWhere
balancean attribute, calculation or aggregate of the same resourceoptimistic and on
arg(:cost)an argument of the action, or an attribute a create acceptsoptimistic only
^context(:key)a field of the record's ctx map, which the server fills (see ctx)optimistic and on
event(:key)a field of the pushed eventon only
has_arg(:name)whether the input carries that keyoptimistic only

A set target must be an attribute or a public calculation of the same resource.

What you cannot read

  • Relationships. author.name fails. Add a calculation or aggregate to the resource and read that.
  • The actor. ^actor(:id) fails. The client does not hold it.
  • Other records. A rule sees the record it belongs to. A reaction (on) sees its own record and the event.

Functions

You writeThe client runs
+ - * /, unary -the same
== !=the same
< > <= >=the same, each side that is not a number literal cast to a number with +
a <> bcat (nested ones become one), each part that is not a text literal wrapped in to_string
x in listin
and, or, notand, or, !
if(cond, then: a, else: b)if
is_nil(x)x == nil
abs(x), round(x), round(x, places), to_string(x), now()custom operations the client must add
has_arg(:name)custom operator has

Everything else is standard JSON Logic. abs, round, to_string, now and has are the five custom operations; a client that evaluates rules has to add them (see "What a client needs" in How it works). now is the current UTC time as ISO 8601 text.

Two rules of the translator keep Ash behaviour on a standard evaluator. Compared values are cast to numbers with +, because Ash sends decimals as text and standard JSON Logic would compare two texts as text ("10.5" would be smaller than "9"). Joined values are wrapped in to_string, because standard cat prints an empty value as null and you expect nothing.

Any other function, such as contains or today(), fails compilation.

Decimals become floats in the rule. Atoms become strings.

Names in the compiled rule

ExpressionJSON Logic variable
balancerecord.balance
arg(:cost)input.cost
^context(:level_up_message)ctx.level_up_message
event(:amount)event.amount

A nested context path is dotted: ctx.copy.title.

What is taken from the action

Before your declared effects, each rule gets set effects read from the action:

  • change atomic_update(attr, expr) becomes set attr, expr.
  • change set_attribute(attr, value) becomes a set when value is a number, a string, an atom or arg(...).
  • A change module that implements AshBackendDrivenOptimisticUi.Change gives the sets that optimistic_sets(opts) returns, with the opts the action passes. They apply every time, and the same rules as any set hold: no relationship, no actor.
  • For a create, every attribute in accept becomes set attr, arg(attr).

Derived sets are marked "source": "derived" in the rule, declared ones "declared". Changes that are a function or a module without optimistic_sets/1, and changes with a where: guard, derive nothing, so a rule never claims more than the action shows. If the same attribute is also declared, the declared set wins.