Locy Rust API Integration¶
Primary Entry Point¶
All Locy operations go through a Session, created from a Uni instance:
Core Methods¶
// Simple evaluation (takes only the program string)
let result = session.locy(program).await?;
// With inline parameters — use the builder, not a params argument
let result = session.locy_with(program)
.param("threshold", 0.5)
.run()
.await?;
// Compile-only check (no evaluation)
let compiled = session.compile_locy(program)?;
// Explain a Locy program — terminal on the builder, returns LocyExplainOutput
let explain = session.locy_with(program).explain()?;
Fluent Builder (LocyBuilder)¶
For advanced configuration, use the builder API:
use std::time::Duration;
let result = session.locy_with(program)
.param("threshold", 0.5)
.timeout(Duration::from_secs(60))
.max_iterations(500)
.with_config(cfg)
.run()
.await?;
Builder methods:
| Method | Description |
|---|---|
.param(name, value) |
Add a named parameter |
.params(map) |
Add multiple parameters |
.timeout(duration) |
Set evaluation timeout (std::time::Duration). Replaces the database query_timeout for this evaluation, above or below it |
.max_iterations(n) |
Set recursion iteration cap |
.with_config(cfg) |
Set full LocyConfig options (taken by value) |
.cancellation_token(token) |
Attach a cancellation token; cancelling it aborts the evaluation with UniError::Cancelled |
.run() |
Execute and return LocyResult |
.explain() |
Compile and return LocyExplainOutput without evaluating |
Config (LocyConfig)¶
Common fields:
max_iterationstimeout(Option<Duration>;None= 300s between strata, databasequery_timeoutinside operators)max_explain_depthmax_slg_depth(deprecated, no effect; using it is a deprecation warning)goal_directed(GoalDirected::Autodefault,Off,On,Shadow): magic-sets evaluation ofQUERY ... WHERE; see Modules, PRIORITY, QUERYreturned_rules(ReturnedRules::Alldefault,Nothing,Only(names)): which rules' facts the result carries inderived_rules(). A rule left out is neither converted to rows nor hydrated for the result; commands are answered the same. A program that derives many facts only toDERIVEa few should passNothingmax_abduce_candidatesmax_abduce_resultsmax_derived_bytesdeterministic_best_bystrict_probability_domainprobability_epsilonexact_probabilitymax_bdd_variablestop_k_proofs
Result Shape (LocyResult)¶
- every rule's facts, through
result.derived_rules().await?(aHashMap<String, Vec<FactRow>>,FactRow = HashMap<String, Value>) orresult.derived_rule(name).await?. Async and fallible: a rule the default goal-directed mode left out is derived on that first read, against the evaluation's snapshot.result.evaluated_rules()is the synchronous view of what the evaluation itself derived;result.lazily_derived_rules()names the rest stats: LocyStatscommand_results: Vec<CommandResult>warnings: Vec<RuntimeWarning>approximate_groups: HashMap<String, Vec<String>>derived_fact_set: Option<DerivedFactSet>— opaque fact set fortx.apply()materialization: every write of a session-level program (DERIVE output and Cypher writes), in program order
Helpers:
result.rows()result.columns()result.stats()result.warnings()result.has_warning(...)result.derived_rule(rule_name).await?result.iterations()
Profile Output (LocyProfileOutput)¶
profile.profile.strata[i].rules[j].iterations[k] is one rule's evaluation in one
fixpoint pass: delta_facts, elapsed_ms, planning_ms / plans (clause bodies are
re-planned every pass), and operators. Besides the physical-plan operators of the clause
bodies, operators lists the steps that run outside a plan, with actual_rows = rows kept:
LocyIsNotAntiJoin(orLocyIsNotComplementunder PROB) — one perIS NOTreference appliedLocyFactDedup,LocyBestByMergeorLocyFoldMerge— the fact merge, once per passLocyProvenance,LocyLineage— proof annotations and shared-proof analysis, when the program records them (anEXPLAIN RULE, top-k proofs, exact inference, or a fold whose proofs can share an event)
profile.profile.phases lists the work done on the derived facts outside the strata, in
the order it ran: pass (initial, re_evaluation, result), kind (strata,
convert, hydrate), the rules and facts covered, and elapsed_ms.
profile.profile.commands lists each dispatched command: kind, elapsed_ms (a
re-evaluation it caused included), facts_written for a DERIVE, and the strata
evaluated and reused before it read its facts.
result.metrics().physical_plans counts every physical plan the program built.
Note: result.rows() returns the rows of the first row-producing command in program order:
a QUERY or a Cypher statement, with an ASSUME { ... } THEN { ... } block searched depth
first through its body's results. The Python rows() method follows the same rule. Use
result.command_results() to reach a specific command's result.
An ASSUME returns CommandResult::Assume { results, derived }: results holds one
CommandResult per body command, in order (a nested ASSUME's own Assume among them), and
derived every rule's facts in the hypothetical state the body's first command reads.
CommandResult::as_assume() returns both; CommandResult::rows() is the first
row-producing result, depth first.
let result = session
.locy("... ASSUME { CREATE (:Marker) } THEN { QUERY linked RETURN a DERIVE link QUERY linked RETURN a }")
.await?;
let (results, derived) = result.command_results()[0].as_assume().expect("an ASSUME");
assert!(matches!(results[1], CommandResult::Derive { .. }));
let after_derive = results[2].rows().expect("the second QUERY's rows");
Explain Output (LocyExplainOutput)¶
explain() is the terminal method on the builder — it compiles the program and returns the logical plan and compilation details without executing it.
Compile-Only (CompiledProgram)¶
let compiled = session.compile_locy(program)?;
println!("strata: {}, rules: {}", compiled.num_strata(), compiled.num_rules());
println!("rule names: {:?}", compiled.rule_names());
Validates the program structure and returns metadata without evaluation.
Authorization¶
When an AuthzPolicy is registered, every Locy evaluation is authorized
before any of it runs: session.locy, tx.locy, their locy_with builders
(run and profile), and prepared programs. The principal is the session's
or transaction's, and the resource path is the program text. A program asks
for:
read, for what it evaluates: rules,QUERY,EXPLAIN RULE,ABDUCE, and read-only Cypher commands;- one more action per command that writes, the action Cypher uses for that
statement:
writefor a Cypher write and forDERIVE,schemafor a DDL procedure,dbmsfor an administrative one (uni.admin.*).ASSUMEmutations ask forwritetoo, although they are discarded.
A DERIVE request names what the equivalent Cypher write would: the labels,
relationship types and inline property keys of the patterns its rule matches
— and of every rule that rule reaches through IS, since those bind what it
writes — together with those it creates (MERGED_WITH for DERIVE MERGE).
A policy keyed on a label therefore sees a derive over that label.
tx.apply(derived) asks for write for each statement it replays, with the
path <locy-apply>. A refused program returns
UniError::AuthorizationDenied and has no effect.