nornicdb-cypher-queries

NornicDB Cypher Query Shapes (Hot-Path Cookbook)

NornicDB has a set of Cypher patterns that the executor recognizes and routes through specialized hot paths. Writing your queries to match these shapes is the single biggest lever for predictable latency. Outside of these shapes you still get correct results, but you fall onto the generic per-row path.

This skill is a menu of proven shapes plus the rules that decide whether the executor accepts them. The full reference with explanatory commentary lives at docs/performance/hot-path-query-cookbook.md.

Generic schema used in examples

• Node labels: EntityA, EntityB, Tenant, Event
• Relationship types: KEY_REL, BELONGS_TO, LINKS_TO
• Properties: primaryKey, alternateKey, tenantId, category, status, createdAt, updatedAt, sessionId

Substitute your own labels/types/properties. The shapes do not depend on the names.

Recommended baseline indexes & constraints

CREATE CONSTRAINT entitya_primarykey_uniq IF NOT EXISTS FOR (n:EntityA) REQUIRE n.primaryKey IS UNIQUE;
CREATE INDEX entitya_alternatekey_idx IF NOT EXISTS FOR (n:EntityA) ON (n.alternateKey);
CREATE INDEX entitya_tenantid_idx IF NOT EXISTS FOR (n:EntityA) ON (n.tenantId);
CREATE INDEX entityb_category_status_createdat_idx IF NOT EXISTS FOR (n:EntityB) ON (n.category, n.status, n.createdAt);
CREATE INDEX entityb_tenantid_idx IF NOT EXISTS FOR (n:EntityB) ON (n.tenantId);
CREATE INDEX event_createdat_idx IF NOT EXISTS FOR (e:Event) ON (e.createdAt);

Composite index order matters — list the index columns in the same order the query uses for filtering and sorting.

---

1. Point lookup & existence

Upsert, then read by stable key

MERGE (n:EntityA {primaryKey: $primaryKey})
SET   n.payload = $payload, n.updatedAt = $now;

MATCH (n:EntityA {primaryKey: $primaryKey})
RETURN n
LIMIT 1;

Lookup by either of two keys (OR → UNION)

CALL {
  WITH $lookupKey AS k
  MATCH (n:EntityA {primaryKey:   k}) RETURN n
  UNION
  WITH $lookupKey AS k
  MATCH (n:EntityA {alternateKey: k}) RETURN n
}
RETURN n
LIMIT 1;

Always prefer this over a single WHERE n.primaryKey = $k OR n.alternateKey = $k predicate — the executor cannot use indexes through cross-property OR.