Queries

Use import { cypher, select, … } from "cyphra" when you depend on the cyphra meta-package, or import from @cyphra/query directly.

Tagged Cypher

Values are always passed as parameters, never string-concatenated into Cypher:

import { cypher } from "@cyphra/query";
 
const { text, params } = cypher`
  MATCH (u:User) WHERE u.id = ${userId} RETURN u
`;

Builder

import { node, rel, prop, eq, select } from "@cyphra/query";
 
const u = node("User", "u");
const o = node("Organization", "o");
const m = rel("MEMBER_OF", "m");
 
select()
  .match(u.out(m, o))
  .where(eq(prop(m.alias, "role"), "admin"))
  .returnFields({ id: prop(u.alias, "id") })
  .orderBy({ prop: prop(u.alias, "createdAt"), direction: "DESC" })
  .skip(0)
  .limit(20)
  .toCypher();

Use u.in(m, from) or u.both(m, other) for incoming or undirected patterns. After match(...), call optionalMatch(pattern) one or more times to append OPTIONAL MATCH clauses in order (then where / return… apply to the full read shape).

where() accepts multiple predicates (AND-combined): eq, neq, gt, gte, lt, lte, between (inclusive (prop >= $lo AND prop <= $hi)), isNull, isNotNull, inList, startsWith, endsWith, contains, matches (=~, Java-style regex; pattern is always a parameter), not(inner), and grouping via and(…) / or(…) (parentheses follow Cypher precedence: AND binds tighter than OR). Example: .where(or(eq(prop(u.alias, "role"), "a"), eq(prop(u.alias, "role"), "b")), eq(prop(u.alias, "active"), true)) → (u.role = $p0 OR u.role = $p1) AND u.active = $p2.

Every value is a Neo4j parameter—only IS NULL / IS NOT NULL have no bound value.

Call returnFields({ … }) or returnStar() before toCypher() (a bare MATCH without RETURN is rejected). Chain returnDistinct() after either to emit RETURN DISTINCT … (deduplicate rows before ORDER BY / SKIP / LIMIT).

Runtime shortcuts

CyphraClient provides queryRecords / queryRecord (from any CompiledCypher) and selectRecords / selectRecord (from a SelectQuery) so you rarely need to wire run + toPlainRecords by hand. See the Runtime page for sessions, transactions, and options.

Codegen

Run cyphra generate to produce cyphra.gen.ts with NodeLabel, RelType, and RelationshipSpec constants aligned to your .cyphra file, then import them alongside the builder for fewer string typos.

Result mapping

@cyphra/runtime exports toPlainRecords and toPlainRecord to turn a session.run / runCompiled result into plain objects (record.toObject()), without an ORM layer.