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 expression | Reads | Where |
|---|---|---|
balance | an attribute, calculation or aggregate of the same resource | optimistic and on |
arg(:cost) | an argument of the action, or an attribute a create accepts | optimistic 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 event | on only |
has_arg(:name) | whether the input carries that key | optimistic only |
A set target must be an attribute or a public calculation of the same
resource.
What you cannot read
- Relationships.
author.namefails. 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 write | The client runs |
|---|---|
+ - * /, unary - | the same |
== != | the same |
< > <= >= | the same, each side that is not a number literal cast to a number with + |
a <> b | cat (nested ones become one), each part that is not a text literal wrapped in to_string |
x in list | in |
and, or, not | and, 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
| Expression | JSON Logic variable |
|---|---|
balance | record.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)becomesset attr, expr.change set_attribute(attr, value)becomes asetwhenvalueis a number, a string, an atom orarg(...).- A change module that implements
AshBackendDrivenOptimisticUi.Changegives the sets thatoptimistic_sets(opts)returns, with the opts the action passes. They apply every time, and the same rules as anysethold: no relationship, no actor. - For a create, every attribute in
acceptbecomesset 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.