Advanced: Modules, PRIORITY, QUERY¶
Modules¶
Modules package reusable rule libraries.
Benefits:
- Reuse and composition.
- Namespace separation.
- Cleaner policy/rule governance.
PRIORITY¶
Priority resolves competing clauses for the same rule relation.
CREATE RULE classify PRIORITY 1 AS MATCH (n) WHERE n.risk > 0.8 YIELD KEY n, 'high' AS level
CREATE RULE classify PRIORITY 2 AS MATCH (n) YIELD KEY n, 'normal' AS level
QUERY¶
QUERY reads a rule's facts as the fixpoint derived them, then filters and
projects them. Ahead of the program's first write command it returns exactly
what .derived holds for that rule; after a DERIVE or a Cypher write it reads
the facts derived again in the state that write left (see
Commands run in sequence).
Evaluation¶
Locy evaluates bottom-up: every rule is derived to its fixpoint before the
first command runs (and again, incrementally, after a command writes). A
QUERY ... WHERE that pins a node KEY column of its rule is the exception:
by default it derives only what that goal can reach. Any other WHERE
filters the derived facts and does not narrow what is derived; to derive less
there, constrain the rule itself (a WHERE in its body, or a REQUIRE).
Goal-directed QUERY¶
A QUERY whose WHERE pins a node KEY column derives only what that goal
can reach (the magic-sets rewrite). This is the default,
LocyConfig.goal_directed = GoalDirected::Auto (from Python, "auto"):
CREATE RULE reach AS MATCH (a:E)-[:T]->(b:E) YIELD KEY a, KEY b
CREATE RULE reach AS MATCH (a:E)-[:T]->(m:E) WHERE m IS reach TO b YIELD KEY a, KEY b
QUERY reach WHERE a.uid = $start RETURN b.uid
On 100 chains of 20 nodes this derives the 19 + 190 facts of the start's chain instead of all 19,000.
- A conjunct binds when it is
key.prop = valueorkey.prop IN [...], withkeya node KEY column and the value a string, integer, boolean or a parameter holding one. Everything else stays a filter, and the wholeWHEREstill applies, so answers never change. - Recursive FOLD / BEST BY / REQUIRE, ALONG, PROB, PRIORITY, generators and
models fall back to full evaluation.
EXPLAIN RULE,DERIVE,ABDUCEand commands insideASSUMEare always fully evaluated. .derivedis unchanged. A rule only rewritten goals needed is not evaluated; it is derived the first time.derivedis read (Rust:result.derived_rules().awaitorresult.derived_rule(name).await), against the snapshot the evaluation read — a commit in between does not reach it — under the same limits, and cached. The first read can therefore fail (a timeout, say); nothing is cached then and the next read tries again.result.lazily_derived_rules()names the rules left out.- Where that could not give exactly what full evaluation gives,
Autoevaluates in full: a program with a write command (DERIVE, a Cypher write), one withEXPLAIN RULE, and every evaluation inside a transaction (tx.locy), whose state cannot outlive the call. A rule left out of an evaluation cut short (allow_partial) is listed inincomplete.skipped_rulesand not derived later. Onleaves such rules out of.derivedinstead (never partial), andGoalDirected::Shadowevaluates every rule while answering from the rewrite; it costs more thanOffand is meant for verification.Offevaluates every rule in full.