OpenCypher Querying¶
Uni uses OpenCypher as its primary query language, with extensions for vector search, time travel, and admin procedures. This keeps graph queries expressive and readable.
id(node) and id(relationship) return signed integer identities. Virtual
entities created by procedures use negative IDs, so id(node) < 0 identifies
a virtual node. Comparisons, ordering and arithmetic use the same integer
returned to the caller; elementId(entity) is its string representation.
What It Provides¶
- Pattern matching for nodes and relationships, including
OPTIONAL MATCHfor left-outer-join semantics. - Aggregations, ordering, filtering, and window functions (
OVERclause). MERGEfor upsert operations withON CREATE SET/ON MATCH SET.SET/REMOVEfor updating properties and labels on existing nodes and relationships.- Procedure calls for algorithms, snapshots, and indexes.
Example¶
use uni_db::Uni;
# async fn demo() -> Result<(), uni_db::UniError> {
let db = Uni::open("./my_db").build().await?;
let session = db.session();
let results = session
.query_with("MATCH (p:Person) WHERE p.age > $min RETURN p.name")
.param("min", 30)
.fetch_all()
.await?;
println!("{:?}", results);
# Ok(())
# }
Semantics Worth Knowing¶
-
MERGE preserves other labels. Matching
(n:A {key: ...})against an existingA:Bnode keeps both labels, including throughON MATCH SETproperty updates and when returninglabels(n). -
Anonymous MERGE deduplicates too. Repeated identical inputs to
MERGE (:Account {key: 'same'})find the node created earlier in the statement, just as a named pattern does. Concurrent conflicting MERGE creates can require a transaction retry, including when the competing write has flushed. -
Recursive queries report budget exhaustion.
WITH RECURSIVEhas a 1,000-round iteration budget. If convergence has not been established within that budget, the query reports an iteration-limit error instead of returning a successful partial result. -
Parameters must be supplied. A query that references
$xwithout a value forxfails withUniError::ParameterMissing { names }before it reads or writes anything -- includingCREATE,SET,MERGEand Locy rules.nameslists every missing parameter of the statement, in order of first appearance (RETURN $a, $bwith no parameters:["a", "b"]), even one in a branch no row would reach.EXPLAINplans without parameters. A parameter supplied asnullis a value, not a missing parameter. - Relationship type disjunctions (
[r:R|Q]) match any listed type, whether each type is declared in the schema or not. - Declared endpoints never drop a match. An edge type's declared source and
destination labels are enforced when edges are written, including by the
bulk loader. A pattern that does not label an endpoint is narrowed to them
only when every stored edge of the type is known to conform: types created
by this release are, types in a store written by an earlier one are
unverifieduntilCALL uni.admin.verifyEdgeEndpoints()(oruni.admin.verifyEdgeEndpoints('R')for one type) finds none violating. Unverified, the pattern reads every vertex and matches violating edges -- correct, but on a large graphMATCH ()-[r:R]->()is much slower (LDBC SF1WORK_AT: about 6 s unverified, 0.3 s verified). The procedure yieldsedge_type,edges_checked,source_violations,target_violationsandconformance; it runs on the primary database, not on a fork.
Use Cases¶
- Relationship queries and graph traversals.
- Pattern matching with filters and aggregations.
- Admin and metadata procedures.
When To Use¶
OpenCypher is the best choice when your data model is graph-shaped and you need expressive relationship queries, not just key-value lookups or SQL tables.
Locy Integration¶
When you need recursive rule-based reasoning, hypothetical analysis, or abductive remediation workflows, use Locy on top of Cypher.
- Start at Locy Overview
- Learn syntax in Locy Language Guide
- See advanced workflows in DERIVE / ASSUME / ABDUCE