Cypher reference

InvariantDB uses openCypher syntax for reads and writes: MATCH, OPTIONAL MATCH, CREATE, MERGE, SET, REMOVE, DELETE, WITH, UNWIND, FOREACH, CALL, aggregates, list comprehensions, and quantifiers. Each node and relationship version also records when the fact was true (valid time) and when it was recorded (transaction time). MATCH accepts AT VALID, AT RECORDED, AS OF, and OVER ... BETWEEN to read at a point in time or across a window, and an AT VALID prefix sets the valid time of a write.

After you sign in, the Reference page in the console lists the built-in procedures with their signatures and output columns, and the Cypher functions. CALL db.listProcedures() lists the procedures on your server.

Reads

// Standard match
MATCH (p:Person {name: 'Alice'})-[:WORKS_AT]->(c:Company)
RETURN p.name, c.name

// At a point in time (real-world)
MATCH (p:Policy) AT VALID '2024-06-01'
WHERE p.holder = 'acme' RETURN p

// As the database knew it at a point in time (transaction)
MATCH (p:Policy) AT RECORDED '2024-06-01' RETURN p

// Both axes at once — "what was true on June 1 according to what we
// knew on June 1"
MATCH (p:Policy)
  AT VALID '2024-06-01'
  AT RECORDED '2024-06-01'
RETURN p

// One row per version whose valid time overlaps a window
MATCH (p:Policy {id: $id})
  OVER VALID BETWEEN '2024-01-01' AND '2024-12-31'
RETURN p.premium, p._valid_from, p._valid_to
ORDER BY p._valid_from

// AS OF t is the same as AT RECORDED t; AT t is the same as AT VALID t
MATCH (p:Policy) AS OF '2024-06-01' RETURN p

// Versions whose transaction time overlaps a window
MATCH (p:Policy {id: $id}) OVER RECORDED BETWEEN '2024-01-01' AND '2024-12-31' RETURN p

// Only versions valid for the whole window
MATCH (p:Policy {id: $id}) OVER VALID COVERING BETWEEN '2024-01-01' AND '2024-12-31' RETURN p

Writes

CREATE (p:Person {name: 'Alice', email: 'alice@example.com'})

MERGE (p:Person {email: 'alice@example.com'})
ON CREATE SET p.created_at = datetime()
ON MATCH  SET p.last_seen = datetime()

// Map-merge: keep existing keys, overwrite supplied
SET p += {a: 1, b: 2}

DELETE p

// Cascade across edges
DETACH DELETE p

// Backdate: the SET is valid from 2024-06-01; the transaction time is now
AT VALID '2024-06-01' MATCH (p:Policy {id: 'p1'}) SET p.premium = 1200

An AT VALID prefix accepts an open start time only; AT VALID ... TO ... and AT VALID BETWEEN ... on a write fail with CLOSED_INTERVAL_WRITE_UNSUPPORTED. DELETE fails on a node that still has relationships; use DETACH DELETE. DELETE ends the entity’s valid time at the time of the write, or at the AT VALID prefix time when the statement has one. Writing a reserved property such as _valid_from (from 1.4.2.5 also _seq) fails with subcode RESERVED_BITEMPORAL_PROPERTY_WRITE. From 1.4.2.5 a CREATE or MERGE that names more than 256 labels new to the graph (the default limit) is refused with 400 TOO_MANY_NEW_LABELS before it runs; labels that already exist do not count. A node in MERGE matches on its labels and every listed property; a node without a label is matched against every node in the graph (a full scan). (Example data is fictional.)

Backdated and future-dated writes

Every write is the entity’s value from its valid start on. The rules below decide what happens when a write starts before the version recorded last, or a delete would end a version before it starts.

// A correction: the amount was 12 from 2022, not 10
AT VALID '2022-01-01'
MATCH (o:Order {id: 'o1'}) AT VALID '2022-01-01'
SET o.amount = 12

// Withdraw a version written for a future date
AT VALID '2031-01-01' MATCH (o:Offer {id: 'x'}) DELETE o   // its valid_from is 2031-01-01

• A write that would replace later-dated versions is refused (from 1.4.2.5). A property or label write (SET, REMOVE, MERGE … ON MATCH SET, a relationship SET) that starts before the current version of its node or relationship would replace, from its start on, every version recorded for a later valid time. When that would change such a version (lose one of its property values or labels, or bring back a property or label a later write removed), the statement is refused with 400 WRITE_WOULD_REPLACE_LATER_VERSIONS and nothing is written; the message names the entity, the start of each later version and what it would lose. This covers a correction under a version recorded for a later time and a write without AT VALID after a scheduled change (AT VALID '<future>' … SET). A write that changes nothing of them is applied. A write without AT VALID is refused only because of a version that was dated in the future when it was written (a scheduled change); concurrent writers, retries and clock differences between writers never cause the refusal. To make the change, write it at or after the latest later version’s start. Through 1.4.2.4 such a write was applied and copied the latest version’s other values into the corrected interval. On the hosted service these writes are refused; a self-hosted operator can choose to apply them instead, in which case the write is based on the version valid at its start, replaces the later versions (also for reads without a time) and warns WRITE_REPLACES_LATER_VERSIONS. From 1.4.3.2, write such a correction with FOR PORTION OF, which keeps the later versions.
• A write at or after the current version’s start (a forward write, a correction at the same instant, a write without AT VALID on a version valid now) is based on the current version and is never refused for this.
• Deletes. AT VALID '<to>' … DELETE with <to> before the version’s start is refused with 400 VALID_END_BEFORE_VALID_FROM (from 1.4.2.4; RUNTIME_ERROR before). From 1.4.2.5 a DELETE or DETACH DELETE without AT VALID is refused the same way when the current version, or a relationship it would remove, starts after the time the statement runs; nothing is deleted. Before, it was accepted and the future-dated fact disappeared at every valid time. A statement that deletes many entities is refused as a whole when one of them is refused. To withdraw a future-dated version, delete it with AT VALID '<its valid_from>'; an entity with a later-dated change recorded can be ended at that time with AT VALID.
• Where a version ends. A version’s end (_valid_to at AT VALID and AT RECORDED reads, validTo in db.history, db.propertyHistory and db.propertyProvenance, the windows of OVER VALID) is the earliest valid start among the writes and deletes recorded after it (from 1.4.2.5; from 1.4.2.4 a version replaced by a write without AT VALID reports its end instead of null). A version that a later-recorded write covers from its own start holds no valid time: validTo equals validFrom, and OVER VALID leaves it out. For writes recorded in valid-time order the end is where the next version starts. Stored history is not rewritten; the ends are computed when read.
• A closed interval on a write (AT VALID FROM x TO y, AT VALID BETWEEN x AND y) is refused with CLOSED_INTERVAL_WRITE_UNSUPPORTED (the subcode from 1.4.2.4; SYNTAX_ERROR before). To create an entity over a closed interval, write the start with AT VALID '<from>' and end it with AT VALID '<to>' … DELETE. To change existing nodes and relationships over a closed interval, use FOR PORTION OF (from 1.4.3.2, below).

Correcting an interval: FOR PORTION OF (from 1.4.3.2)

FOR PORTION OF VALID FROM <from> TO <to> before a statement that matches nodes or relationships and sets or removes properties or labels applies the change to the valid interval from <from> up to, not including, <to>, and keeps everything outside it (the SQL:2011 UPDATE … FOR PORTION OF).

AT VALID '2020-01-01T00:00:00Z' CREATE (o:Order {id: 'o1', amount: 10, status: 'open'})
AT VALID '2024-01-01T00:00:00Z' MATCH (o:Order {id: 'o1'}) SET o.status = 'paid'

// The amount was 12 from 2022 to the end of 2024, not 10
FOR PORTION OF VALID FROM '2022-01-01T00:00:00Z' TO '2025-01-01T00:00:00Z'
MATCH (o:Order {id: 'o1'})
SET o.amount = 12

• What it changes. Each version of the entity in the interval gets the change. A version that starts inside the interval keeps its other values (the 2024 status = 'paid' above); a version that runs into <from> or across <to> is split there, and its values outside the interval stay as they were. Without TO the change applies from <from> on. An entity whose first version starts after <from> is changed from that start; an entity whose versions all start at or after <to> is not changed.
• Never refused for later versions. It never replaces a later version, so it is never refused with WRITE_WOULD_REPLACE_LATER_VERSIONS. It is the way to correct the past under a later-dated version.
• Times. <from> and <to> take what AT VALID takes: an ISO 8601 string, integer nanoseconds or a parameter (FOR PORTION OF VALID FROM $from TO $to). TO must be after FROM.
• What it can write. SET n.p = v, SET n += {…}, REMOVE n.p, SET n:Label, REMOVE n:Label and relationship properties (SET r.p = v). A SET value is written to every version in the interval, so it must be a literal, a parameter or a value computed from them (UNWIND $rows AS r MATCH (n {id: r.id}) SET n.p = r.v), not a value read from the graph (SET o.amount = o.amount + 1 is refused).
• Reads. All of it is written at one recorded time. AT VALID reads, _valid_from / _valid_to, OVER VALID, db.history, db.propertyHistory and db.propertyProvenance show the split; AT RECORDED before the statement reads the versions as they were. A RETURN in the statement shows each entity’s current record.
• A TO in the future. The old value comes back at <to>, so the entity then has a scheduled change; a read without a time answers the corrected value until then.
• Constraints. NOT NULL, NODE KEY and property types are checked on every version the statement changes; uniqueness on the current records.
• Cost. The statement writes one version for each version of the entity in force from <from> on.

Refused with 400 PORTION_WRITE_UNSUPPORTED (MCP -32006), with nothing written: a clause other than MATCH, OPTIONAL MATCH, WITH, UNWIND, SET, REMOVE and RETURN (so no CREATE, MERGE, DELETE, FOREACH or CALL), UNION, a statement without SET or REMOVE, a MATCH, UNWIND or WITH … WHERE after the first SET / REMOVE, SET n = {…}, a SET value read from the graph, TO at or before FROM, relationships of a type that a relationship constraint with a quote check covers, adding or removing a label that a relationship constraint names, an entity deleted for a while inside the restated interval, and an entity whose history cannot be read. A statement too large to commit at once is refused with BATCH_TOO_LARGE (it is never committed in parts), and a caller whose writes an access policy restricts gets ACCESS_POLICY_SURFACE_UNAVAILABLE. FOR PORTION OF RECORDED, and FOR PORTION OF together with an AT VALID prefix, are syntax errors. There is no DELETE … FOR PORTION OF: mark the interval with a property or a label (FOR PORTION OF VALID FROM … TO … MATCH (n …) SET n:Inactive). In db.propertyProvenance, a value the statement restated without changing it can show the statement’s provenance; the writes that set the value stay in db.history and in AT RECORDED reads.

Aggregation

Pattern features

// Variable-length paths
MATCH path = (a)-[*1..5]->(b) WHERE a.id = $start AND b.id = $end RETURN length(path)

// Named paths
MATCH p = (a)-[r]->(b)
RETURN length(p), nodes(p), relationships(p)

// shortestPath as an expression; both endpoints must be bound first
MATCH (a:Person {id:$a}), (b:Person {id:$b})
RETURN shortestPath((a)-[:KNOWS*]->(b)) AS p

// Node ids and hop count
MATCH (a:Person {id:$a}), (b:Person {id:$b})
CALL gds.shortestPath(id(a), id(b)) YIELD path, length
RETURN path, length

// Pattern comprehension
MATCH (a:Person {id:$id})
RETURN [(a)-[:KNOWS]->(friend) WHERE friend.active | friend.name] AS active_friends

// Quantifier predicates
MATCH (p:Project)
WHERE ANY(x IN p.tags WHERE x STARTS WITH 'urgent')
  AND ALL(c IN p.checks WHERE c.passed)
RETURN p

// reduce()
RETURN reduce(s = 0, x IN [1, 2, 3] | s + x * x) AS sum_of_squares

shortestPath and allShortestPaths also work as a pattern: MATCH p = shortestPath((a)-[:KNOWS*]->(b)). The search uses the direction, relationship types, property map and length bounds of the pattern; a lower bound above 1 is refused. When no path exists, shortestPath(...) returns null, allShortestPaths(...) returns an empty list, and the MATCH form returns no row. length(p), nodes(p) and relationships(p) work on the returned path. In a MATCH pattern outside shortestPath, a variable-length pattern without an upper bound stops at 10 hops.

WHERE conditions

// Standard comparison
WHERE n.score >= 0.5 AND n.label IN ['A', 'B']

// Regex
WHERE n.name =~ '(?i)alice.*'

// String predicates
WHERE n.name STARTS WITH 'A'
WHERE n.url ENDS WITH '.com'
WHERE n.body CONTAINS 'pricing'

// Not-equals
WHERE a.x <> b.x

// Null handling
WHERE n.email IS NULL
WHERE n.email IS NOT NULL

Aggregating subqueries

// COUNT { ... } — Cypher-5 count subquery
RETURN COUNT { MATCH (a:Person {name:'Alice'})-[:KNOWS]->() } AS friend_count

// CALL { ... } — sub-query with parameters
MATCH (a:Account {id:$id})
CALL {
  WITH a
  MATCH (a)-[:OWNS]->(p:Position)
  RETURN sum(p.value) AS total
}
RETURN a.id, total

From 1.4.2.3 a CALL { } body sees an outer variable only through a WITH as its first clause, as above. A body without one that reads an outer variable, or names it in a pattern, is refused with 400 UNRESOLVED_VARIABLE before anything runs; through 1.4.2.2 such a body used the outer value. A body without an importing WITH that returns a column under the name of an outer variable (WITH 1 AS t CALL { UNWIND [5] AS t RETURN t } RETURN t) is refused with SEMANTIC_ERROR, as on Neo4j (from 1.4.2.5). A name the body declares itself (UNWIND … AS t, WITH x AS t, YIELD t, the variable of a list comprehension) is a new variable (from 1.4.2.5; 1.4.2.3 and 1.4.2.4 refused these). From 1.4.2.5 a body may hold a procedure call and further CALL { } bodies, nested up to 8 levels; subqueries of every kind nest at most 32 levels (400 EXPRESSION_TOO_DEEP). A body without RETURN keeps the outer rows as they are. Neo4j’s CALL (a, b) { … } import form and CALL { } IN TRANSACTIONS are not supported.

Indexes

// Property index on current values
CREATE INDEX FOR (n:Person) ON (n.email)
DROP INDEX FOR (n:Person) ON (n.email)

// Vector index over vectors stored in a node property
CALL db.buildVectorIndex('Doc', 'embedding')

// List property indexes and vector indexes
CALL db.listIndexes()
CALL db.listVectorIndexes()

Declaring the vector property in the graph schema (type vector, dim N) is optional. With a declared dim, creating a node (CREATE or MERGE) with a vector of a different dimension is refused; SET on an existing node is not checked.

From 1.4.1, CREATE INDEX on a label that has no value for the property yet takes the type of the first value written and returns the warning INDEX_TYPE_PENDING; until that value is written, reads of the property scan the label. To set the type at once, add OPTIONS {value_type: 'string'|'int'|'float'|'bool'}. CREATE INDEX again on an index that holds no value because every stored value has another type rebuilds it with that type and returns the warning INDEX_RETYPED.

From 1.4.3.3, CREATE INDEX on a label with 100,000 nodes or more returns at once: the index is registered and built in the background, and the statement carries the info warning INDEX_POPULATING with details.build_id and details.value_type. CALL db.listIndexes() shows the index as populating until it is online; meanwhile reads of the label scan it, with the same answers. A CREATE INDEX sent while another build runs on the graph is accepted and its build queued. Smaller labels are indexed before the statement returns, as before. db.listIndexes() yields a new last column, value_type (int, string, float or bool; null on a relationship index until its type is chosen).

Relationship property indexes (from 1.4.3.2)

CREATE INDEX FOR ()-[r:HAS_MEMBER]-() ON (r.joinDate)
CREATE INDEX member_note FOR ()-[r:HAS_MEMBER]->() ON (r.note) OPTIONS {value_type: 'string'}
DROP INDEX FOR ()-[r:HAS_MEMBER]-() ON (r.joinDate)

// Answered from the index
MATCH (friend)<-[m:HAS_MEMBER]-(forum) WHERE m.joinDate > $minDate RETURN forum

An index covers one property of one relationship type; the direction of the arrow does not matter. CREATE INDEX builds the index before it returns: it rewrites the graph’s files once, so on a large graph it takes as long as a full maintenance pass. Repeating it, or dropping an index that does not exist, does nothing. Without value_type the index takes the type most stored values have. db.listIndexes() lists it with type relationship_range, name ()-[:TYPE]-().prop and state online, or populating while it is declared but not built.

A MATCH … WHERE r.prop <op> value on a relationship of exactly that type is answered from the index when <op> is =, <, <=, > or >= with an integer, or = with a string, and nothing else in the statement reads that relationship. The answers are the same as without the index: relationships written since the last maintenance pass are checked on their records. The index is not used when a stored value of the property has another type than the index, for a statement with a time clause, for a caller that a field read rule may deny the property, or in a statement the planned query engine does not run (statements that write, PROFILE, UNION, subqueries, credentials an access policy restricts). EXPLAIN shows RelIndexFilter when it is used.

Constraints

// Unique value per label; the name is optional; IF NOT EXISTS before or after the name
CREATE CONSTRAINT person_email IF NOT EXISTS FOR (p:Person) REQUIRE p.email IS UNIQUE

// Unique combination, and node key (present, not null, unique combination)
CREATE CONSTRAINT FOR (o:Order) REQUIRE (o.region, o.number) IS UNIQUE
CREATE CONSTRAINT FOR (o:Order) REQUIRE (o.region, o.number) IS NODE KEY

// Property must be present and not null; property type
CREATE CONSTRAINT FOR (p:Person) REQUIRE p.name IS NOT NULL
CREATE CONSTRAINT FOR (p:Person) REQUIRE p.age IS :: INTEGER

// From 1.4.2: required relationship (every Claim has a SUPPORTED_BY relationship to a Passage),
// and the same with the quote check
CREATE CONSTRAINT claim_supported FOR (c:Claim) REQUIRE (c)-[:SUPPORTED_BY]->(:Passage)
CREATE CONSTRAINT claim_quoted FOR (c:Claim) REQUIRE (c)-[:SUPPORTED_BY]->(:Passage) OPTIONS { quote: true }

// List constraints; check existing data against them
CALL db.constraints()
CALL db.validateConstraints()

// Drop by name
DROP CONSTRAINT person_email
DROP CONSTRAINT notnull_Person_name IF EXISTS

Every write is checked against every constraint before anything is stored: CREATE, MERGE, SET, SET n:Label, REMOVE, writes inside FOREACH and CALL { }, the AT VALID prefix, string-id command batches, imports and MCP tools. Duplicates inside one statement are refused. Unique values are checked on the statement’s final state, so a statement that swaps values between nodes is accepted.

A violation applies nothing of the statement and answers HTTP 409, code ENG_SCHEMA_VIOLATION, subcode CONSTRAINT_VIOLATION (MCP: JSON-RPC -32009), with details naming the constraint, label, properties, reason and, for a duplicate, the string id of the node that already holds the value. In a string-id command batch, three refusals that are not declared constraints answer 400 with the same subcode: a MergeNode whose key matches more than one node (details.constraint merge_key_unique), a delete of a node that still has relationships (connected_edges), and a vector of the wrong dimension or type for a declared vector property (vector_schema). A Cypher MERGE whose pattern matches more than one node binds every match.

CREATE CONSTRAINT checks the existing data first and is refused with 409 CONSTRAINT_CREATION_FAILED (up to ten offending node ids) if any node violates it. A name that already exists answers 409 SCHEMA_RULE_ALREADY_EXISTS, and the same rule under another name 409 EQUIVALENT_SCHEMA_RULE_ALREADY_EXISTS; with IF NOT EXISTS both are no-ops. A unique constraint without an index on its property creates one; that index is dropped with the constraint. On a large label, create the index first. A constraint is durable when the statement returns.

Required relationships (from 1.4.2). REQUIRE (c)-[:T]->(:M) says that a node of the label cannot exist without a relationship of type T, in the stated direction, to a node with label M; (c)<-[:T]-(:M) requires an incoming one and (c)-[:T]->() accepts any node at the other end. The requirement is one relationship with one type and a direction; a variable length, several types, property maps and longer patterns are refused. The rule is checked at the end of every write, on the state the write leaves, so the order of clauses does not matter. Refused, with nothing applied: creating a node with the label or adding the label without the relationship; deleting the last such relationship of a node that keeps the label; deleting the node at the other end, or removing its label, when that leaves a node without the relationship. Create the node and its relationship in one statement or one batch: MATCH (p:Passage {id: $passage}) CREATE (c:Claim {id: $id})-[:SUPPORTED_BY]->(p). To retract a node, delete it with DETACH DELETE, or remove its label in the statement that removes its relationship. A refusal answers 409 CONSTRAINT_VIOLATION with details.constraint required_relationship, details.reason, details.relationship and details.node_id. db.constraints() lists the constraint with type REQUIRED_RELATIONSHIP and the columns relationshipType, direction, targetLabel and options. IF NOT EXISTS is a no-op only when the existing constraint has the same requirement and the same options; otherwise the statement is refused.

Quote check (from 1.4.2). With OPTIONS { quote: true } each required relationship carries quote (a string), start and end (integers; end is exclusive), and the quote must equal the other node’s text at those positions. Positions count Unicode code points from 0, as substring() does; both sides are put in Unicode NFC and compared byte for byte, so case, white space and punctuation must match. An empty quote is refused, and a span cannot split a letter from its combining mark. The server stores the SHA-256 of the quote in quote_sha256 on the relationship. A write that changes a quoted span of the text is refused; change the text and its quotes in one statement. The options text_property, quote_property, start_property, end_property and hash_property set other property names. details.reason is unsupported (no relationship), quote_missing, quote_mismatch or quote_hash; the refusal does not repeat the quote or the text. With the option on, a node satisfies the constraint when it has at least one such relationship and every one it has passes the check.

Access control by label and relationship type

From 1.4.2 a graph can carry an access policy. The policy says which nodes and relationships each subject (the id of a credential: a user, an API key, an agent) may read and write, by label and by relationship type. A graph without a policy behaves as before, and upgrading does not change existing graphs. Field access rules still decide which properties of a visible node a caller reads.

// Deny by default; analysts read documents and the links between them
CALL db.access.setDefault('deny')
CALL db.access.grant('analyst', 'read', 'label', 'Document')
CALL db.access.grant('analyst', 'read', 'relationship_type', 'CITES')

// Hide one label from analysts, whatever else they are granted
CALL db.access.deny('analyst', 'read', 'label', 'Privileged')

// Give the role to an API key (the subject id that db.access.whoAmI() reports for it)
CALL db.access.assignRole('apikey:k_3f2a', 'analyst')

// Why can or can't a subject read a node?
CALL db.access.why('apikey:k_3f2a', 'doc-118', 'read', ['analyst'])
  YIELD allowed, rule, role, target, restriction, policyVersion
RETURN allowed, rule, role, target, restriction, policyVersion

A role holds allow and deny rules for the privileges read, write and grant on the whole graph, one label or one relationship type. A subject holds the roles its credential carries plus the roles the policy assigns to its id. A decision is made in this order: a mandatory restriction that applies to the subject and names one of the node’s labels refuses; a deny rule of any of the subject’s roles refuses; an allow rule permits; otherwise the graph’s default (allow or deny) decides. A grant on one label never overrides a deny or a restriction on another label of the same node. A relationship is visible only when its type is allowed and both of its end nodes are visible.

Reads. For a subject the policy restricts, a node or relationship it may not read is absent: MATCH does not bind it, a path does not pass through it, count(*) and every aggregate leave it out, and ORDER BY ... LIMIT ranks only what the subject sees. The result carries no warnings and no plan statistics.

Writes. Changing or deleting a node needs write on the node, and the node must be visible. Creating a node with a label, adding a label and removing a label each need write on that label. A relationship write needs write on its type, with both end nodes visible. MERGE matches only nodes the subject can see. A refused write answers HTTP 403, subcode ACCESS_DENIED; the refusal names no label, relationship type or value that the caller did not supply.

Changing the policy. A credential with the role admin or tenant_admin can make any change. Any other subject needs grant on the target of each rule it adds or removes, and can grant only a privilege it holds. Removing a deny rule, editing restrictions and changing the default need admin or tenant_admin. Each accepted change is recorded with the subject that made it, the time and a SHA-256 link to the previous change, and applies to every statement that starts after the call returns. db.access.events() reads the recorded changes and db.access.verifyChain() checks their hash chain. A statement that changes the policy cannot also write data (FORBIDDEN_MIXED_SCHEMA_AND_DATA).

The procedures that change the policy return version, action and ownHash. db.access.policy, db.access.events, and db.access.why about another subject need admin, tenant_admin or a subject that holds grant.

Procedures

This page lists common procedures. Other built-in procedures cover index and constraint listing (db.listIndexes, db.constraints, db.validateConstraints, db.listVectorIndexes), vector indexes (db.buildVectorIndex, db.dropVectorIndex, db.embedBackfill, gds.embedText), decisions (db.recordDecision, db.exportDecisionTrail), relabeling (db.relabel), counts (db.graphCounts; from 1.4.1 db.labelCounts), and, from 1.4.2, the access policy (db.access.*, see Access control). CALL db.listProcedures() YIELD name, signature, description, status lists each procedure on your server with its signature. After you sign in, the Reference page in the console shows the same list.

Name only the output columns a procedure produces in YIELD; an unknown column fails with subcode UNKNOWN_YIELD_COLUMN.

Time + history

db.changes and db.delta take integer nanoseconds since the Unix epoch; ISO strings are not accepted. To select changes by ISO date, use DIFF GRAPH FROM '2025-06-01' TO '2025-07-01'.

Provenance + lineage

Recording provenance

Send a provenance object with a write to POST /cypher, POST /graphs/{name}/cypher, or the MCP cypher_query tool. It applies to each property value the statement writes.

{
  "query": "MATCH (p:Policy {id: 'p1'}) SET p.premium = 1200",
  "provenance": {
    "actor": "underwriter-17",
    "source": "pricing-service",
    "reason": "annual review",
    "requestId": "req-8841",
    "confidence": 0.9
  }
}

All fields are optional. confidence is a number from 0 to 1 (a numeric string is also accepted); any other value fails with HTTP 400, subcode INVALID_PROVENANCE_CONFIDENCE (an invalid-params error on MCP), and nothing is written. Over HTTP you can send the same fields as X-Provenance-Actor, X-Provenance-Source, X-Provenance-Reason, X-Provenance-Request-Id, and X-Provenance-Confidence headers with ASCII values; a body field takes precedence over its header. On an authenticated request the server also records principal, the identity of the credential that made the write. Clients cannot set principal. Send provenance: {} to record only the principal. On 1.4.1 and earlier, requests without a provenance object or header record no provenance. From 1.4.2 every write of an authenticated request records principal, with or without a provenance object, on the Cypher routes, /execute and the MCP tools; a principal sent in the object, the body or a header is not used. principal stays null for unauthenticated writes, for writes made before 1.4.2 without a provenance object, for import and ingest jobs and other background jobs, and for the legacy POST /write route. After a host failure the principal of the last writes before it can be missing. Any caller that may run db.history or db.propertyProvenance on a graph sees the credential ids of its writers.

MATCH (p:Policy {id: 'p1'})
CALL db.propertyProvenance(id(p), 'premium')
  YIELD value, txnAt, actor, source, reason, requestId, confidence, principal
RETURN value, txnAt, actor, source, reason, requestId, confidence, principal

Consecutive versions with the same value are returned as one row. txnAt, validFrom, and validTo are nanoseconds since the Unix epoch. (Example values are fictional.)

Agent memory

Compliance

Graph algorithms and search

Full-text indexes (from 1.4.3)

A declared full-text index stores the words of one text property of one label with their positions and their sentence and paragraph boundaries. It answers phrases, AND / OR / NOT, prefix and wildcard words, words within n words of each other, and words in the same sentence or paragraph, in four query syntaxes. It is built in a fixed amount of memory, so labels of any size can be indexed, and after the build it follows the data: a write is in the answer of the next query. A query can return the matching passages of the stored text with their offsets. gds.fulltextSearch (any word, BM25, no index to declare) answers as before.

// Declare and build (in the call; use {build: 'background'} for a large label)
CALL db.createFulltextIndex('Opinion', 'text')
YIELD status, state, docs, bytes, buildMillis

// Query: legal terms and connectors, 20 hits per page
CALL db.fulltext.query('Opinion', 'text', 'negligen! /s duty', {syntax: 'legal', k: 20})
YIELD node, score, total, complete, cursor
RETURN node.title, score, total, complete, cursor

// Matching passages with offsets
CALL db.fulltext.query('Opinion', 'text', '"deliberate indifference" /p "serious medical need"',
                       {syntax: 'legal', snippets: {max: 2, words: 30}})
YIELD strId, score, snippets

CALL db.listFulltextIndexes() YIELD label, property, state, docs, reason
CALL db.dropFulltextIndex('Opinion', 'text') YIELD dropped

Declaring. Options of db.createFulltextIndex(label, property [, options]): analyzer ('unicode-v2', the default, or 'ascii-v1', the tokenizer of gds.fulltextSearch), fold_accents (true: e also matches é; default false), stem ('none', the default, or 'english'), sentence_abbreviations ('legal-en', the default, or a list of words after which a period does not end a sentence), paragraph_break ('blank_line', the default, or 'line'), history ('current', the default, or 'all'; see below), build ('now', the default, 'background' or 'none') and rebuild (true rebuilds an existing index). A second call with the same options keeps the index (status: 'exists'); one with other options is refused with FULLTEXT_INDEX_EXISTS (drop the index first; history is not changed in place). A build in the call is stopped by the statement time limit and then removes its declaration. The graph takes writes while an index is built. Refused: an unknown option (FULLTEXT_OPTION_INVALID), a property declared encrypted (FULLTEXT_PROPERTY_ENCRYPTED), a reserved property name, too little free disk (FULLTEXT_DISK_INSUFFICIENT), and a build while another heavy operation runs on the graph (HEAVY_OPERATION_IN_PROGRESS). Declaring or dropping an index needs a credential that may write to the graph. db.listFulltextIndexes() returns one row per index with state (ready, building or rebuild_required, with reason; the server rebuilds such an index in the background, except one declared with build: 'none' and never built; build it with another db.createFulltextIndex call), docs, bytes, progress while a build runs, and pendingChanges.

Querying. Options of db.fulltext.query(label, property, query [, options]): syntax ('words', the default, 'legal', 'lucene', 'fts5'), default_operator ('or', the default, or 'and': what a space means in legal and lucene), k (1 to 10,000; default 10), order ('score' or 'node'), cursor, max_expansions (default 256), snippets, total (default true; false returns the best k only, with total and cursor null, and is faster for words joined by OR; it cannot be combined with cursor), at_valid and at_recorded. Columns: node, nodeId, strId, score (BM25), matches, snippets, total (the exact number of matching documents), complete (no match follows this page), cursor (pass it back for the next page; null on the last page), parsed (the query as it was read) and stale. A cursor is valid while the documents of the index do not change; after a write to the label the next page is refused with FULLTEXT_CURSOR_STALE, so run the query again from the first page.

lucene takes AND, OR, NOT, +a, -a, phrases, "a b"~2, neglig* and wom?n; fields, boosts, fuzzy search and ranges are refused. fts5 is the SQLite FTS5 MATCH syntax (a space means AND; NEAR(a b, 5), ^a, neglig*). words matches a document that holds any of the words, with the scores of gds.fulltextSearch for the same analyzer.

Words. unicode-v2 splits text at Unicode word boundaries, applies NFKC normalization and case folding, and indexes the letters and digits of every script; Chinese, Japanese and Korean text is indexed as overlapping pairs of characters. A word with periods is also indexed without them (U.S.C. also as usc) and a possessive also without 's (defendant's also as defendant). A sentence does not end after a listed abbreviation (v., U.S., Inc., F.2d, …) or a one-letter initial. A query word that holds no indexed word (§) is dropped with the warning FULLTEXT_QUERY_TERM_EMPTY.

Snippets. snippets: true returns up to 3 passages of about 40 words per hit; {max: 1-10, words: 5-200, unit: 'words' | 'sentence'} sets the number, the length and whether whole sentences are returned. Each passage is an exact substring of the stored value, with its range in UTF-8 bytes, characters and UTF-16 code units (startByte, endByte, startChar, endChar, startUtf16, endUtf16; end exclusive), the sentence and paragraph it starts in, and highlights, the matches inside it with the same offsets. A phrase or a proximity match is one highlight. A snippet is made only from text the caller may read. The text analysed for one page of snippets is limited; past the limit the call is refused with FULLTEXT_QUERY_TOO_EXPENSIVE (ask for a smaller page).

Reads at a past time. An index declared with {history: 'all'} also answers reads at a time: the at_valid and at_recorded options (an ISO 8601 string or nanoseconds; together or alone), or an AT VALID '<t>' prefix on a read-only statement. The documents are the nodes that MATCH (n:Label) returns at that time, with the text, scores, total, node and snippets of that time: a node deleted since is found, one created later is not. The first read of a time can take longer on a label that changed much since then; later reads of the same time are fast until the graph takes a write. A read that needs too much text from the history is refused with FULLTEXT_QUERY_TOO_EXPENSIVE. An index without history: 'all' refuses such a read with FULLTEXT_HISTORY_NOT_INDEXED. A read without a time on a label that holds a version whose valid time starts later answers what is valid now: an index with history: 'all' is read at now, and one without answers from the current text with the info warning FULLTEXT_VALID_NOW_CURRENT_TEXT.

Field read rules. A caller that the index’s own label denies the property is refused, as for gds.fulltextSearch. A document whose node has another label whose field read rule hides the property from the caller is left out before ranking: it is in no hit, page, total, score or prefix expansion, and the answer is that of an index built from the documents the caller may read. A cursor belongs to the documents its query could see. At a past time the rule is applied to the labels each node had then.

Erasure. db.destroySubjectKey removes the contents of every declared full-text index of the graph; the indexes answer FULLTEXT_INDEX_REBUILD_REQUIRED until the server has rebuilt them in the background. A full-text index cannot be declared on a property declared encrypted (FULLTEXT_PROPERTY_ENCRYPTED). An index built before its property was declared encrypted still holds the text written before, and is refused with FULLTEXT_PROPERTY_ENCRYPTED until you drop it with db.dropFulltextIndex; a crypto-shred removes its contents. Text stored unencrypted is still stored after a crypto-shred, and a rebuild indexes it again.

Refusals, never a cut-short answer. FULLTEXT_INDEX_NOT_FOUND, FULLTEXT_INDEX_BUILDING (HTTP 503; retry), FULLTEXT_INDEX_REBUILD_REQUIRED, FULLTEXT_QUERY_SYNTAX (with the character position), FULLTEXT_QUERY_UNSUPPORTED, FULLTEXT_EXPANSION_TOO_BROAD (a prefix or wildcard word expands to more than max_expansions terms, or all of them together to more than 4,096 or max_expansions when larger), FULLTEXT_QUERY_TOO_EXPENSIVE, FULLTEXT_CURSOR_INVALID, FULLTEXT_CURSOR_STALE, FULLTEXT_HISTORY_NOT_INDEXED, FULLTEXT_OPTION_INVALID. FULLTEXT_INDEX_STALE is returned only by a read-only server that has not loaded the data the index covers.

Search routes, MCP, hybrid search and recall. POST /graphs/{name}/search/fulltext and the MCP tool search_fulltext take index ('auto', the default, 'declared' or 'adhoc') and the query options above. With 'auto', a declared index on the label and property answers, and the response adds index: "declared", total, complete, cursor, parsed and stale, and per hit str_id, matches and, when asked, snippets. This changes one answer: on a label and property with a declared index, a request with no new field is answered by the declared index; send index: 'adhoc' for the 1.4.2.5 answer. While the declared index is being built or must be rebuilt (for example after db.destroySubjectKey), these requests answer 503 FULLTEXT_INDEX_BUILDING or 400 FULLTEXT_INDEX_REBUILD_REQUIRED; index: 'adhoc' answers meanwhile. POST /graphs/{name}/search with mode: 'bm25' is also answered by a declared index on the label and property when one is declared (hits {node_id, str_id, score}); it takes no index field, so use /search/fulltext with index: 'adhoc' for the 1.4.2.5 answer. Graphs without a declared index answer as before. gds.fulltextSearch takes a 7th argument {analyzer} ('ascii-v1', the default, 'unicode-v2', 'unicode-v2+fold', 'unicode-v2+stem', 'unicode-v2+fold+stem'), and so do the search routes and the MCP tool; with a Unicode analyzer the warning FULLTEXT_TOKENIZER_LIMITED is not raised. The 9th argument of db.hybridSearch also takes analyzer, or index: 'declared' to read the declared index for the keyword side. Memory recall (POST /graphs/{name}/memory/recall, MCP recall) reads a ready declared index on the recalled label and property for its keyword side, so memories in every script are found by keyword: CALL db.createFulltextIndex('Event', 'text') for the MCP memory tools.

Several fields, filters, matched words, excerpts, pages (from 1.4.3.3)

// Several fields with weights
CALL db.fulltext.query('Fact', {said: 1.0, who: 2.0, role: 0.5}, 'injury claim')
YIELD node, score, fieldScores

// Filter before ranking
CALL db.fulltext.query('DocumentPage', 'body', '"duty of care"',
                       {syntax: 'legal', filter: {case_id: $matter}, k: 20})
YIELD node, score, total

// Best page of each document, with an excerpt
CALL db.fulltext.query('DocumentPage', 'body', 'negligen! /s duty',
                       {syntax: 'legal', group_by: 'document_id', filter: {case_id: $matter}, excerpt: true, k: 20})
YIELD node, score, group, groupHits, excerpt
RETURN group AS document, node.page AS page, score, groupHits, excerpt

These options need a declared index. A query that uses none of them answers as before, with the same columns.

Several fields. The property argument may be a list of properties (['said', 'who'], weight 1 each) or a map of property to weight (a number above 0, at most 1,000,000). Each property needs a declared index on the label; at most 16 fields. A document is a hit when the query matches in at least one field. Its score is the sum, over the fields it matched in, of the weight times its BM25 score in that field, and fieldScores maps each field to that field’s score. Ties are ordered by node id; total counts the documents that match in any field. Every match of each field is ranked, so a query of several fields is not paged by cursor (refused with FULLTEXT_OPTION_INVALID); ask for a larger k (at most 10,000). A field with too many matches is refused with FULLTEXT_QUERY_TOO_EXPENSIVE. A node is left out when a field read rule hides any of the fields from the caller.

Filter before ranking. filter takes the grammar of the gds.vectorSearch filter: {prop: value}, {prop: [v1, v2]} (up to 1,000 values), {prop: {gt|gte|lt|lte: v}}, up to 8 properties joined by AND; a null, missing or incomparable value does not pass. nodeIds lists the nodes that may be hits (node ids, string ids or nodes, for example collect(n) of a MATCH); with a filter, a node must be listed and pass. A node that does not pass is not a hit: it takes no place on a page and is not counted in total. Pages by cursor walk the passing hits; a cursor of one filter is refused with another (FULLTEXT_CURSOR_STALE). With filter_statistics: 'collection' (the default) the scores are those of the search without the filter, and the page is exactly the first k passing hits of the whole ranking; with 'filtered' the scores are those of an index built from the passing documents alone. At a past time the filter is checked on each node’s version at that time, so a node moved to another matter later is found in its old matter; 'filtered' with a filter is refused at a past time (pass nodeIds from a MATCH at the same time instead). The caller must be able to read every filtered property on the label.

Matched words. matched_terms: true adds matchedWords, the words of the stored text that made the node a hit, as written and lowercased, and matchedTerms, the same words as the index holds them (after stemming and accent folding). A phrase gives each of its words.

Excerpts. excerpt: true or {start, end, ellipsis, words} (defaults [, ], … and 12) adds excerpt: the hit’s best passage of about words words with every match marked, and an ellipsis where the passage does not start or end the value. A phrase is one mark from its first word to its last. The text outside the marks is the stored text unchanged. With several fields the excerpt comes from the field with the highest weighted score. For offsets or several passages, use snippets.

Pages and documents. A declared index holds whole bodies of any length. To return the page a match is on, store pages as nodes of their own (:DocumentPage {document_id, page, body}), declare an index on the page body and group the hits by document. group_by: <property> returns one row per value of the property, the best hit of the group, with group (the value) and groupHits (the number of hits in the group); total counts groups. A hit without the property is a group of its own with group null. group_by ranks every match first, so it is not paged by cursor, and a query with too many matches is refused with FULLTEXT_QUERY_TOO_EXPENSIVE. A match that spans two pages is found by an index on the whole body, not by the page index; query both when that matters.

Search routes and MCP. POST /graphs/{name}/search/fulltext and the MCP tool search_fulltext take fields (the list or the map; it must include property), filter, node_ids, filter_statistics, matched_terms, excerpt and group_by. Each hit then has field_scores, matched_words, matched_terms, excerpt, group and group_hits as asked. Bad values are refused with FULLTEXT_OPTION_INVALID.

Reads at a past time after other changes. From 1.4.3.3, a read of an index declared with history: 'all' at a past time keeps the current document of a node whose text and labels at that time equal its current ones (because only another property changed since), instead of reading its text from the history again. The answers are the same; such a read after many changes to other properties no longer runs into FULLTEXT_QUERY_TOO_EXPENSIVE.

Not available: row-level access rules, the text of earlier versions stored in the index (a read at a past time reads it from the graph’s history), and one index over several labels. From 1.4.3.3 several properties are searched together by naming several declared indexes (above).

Hybrid search: fusion, weights and reads at a past time (from 1.4.3.3)

CALL db.hybridSearch('Fact', 'said', $q, 'text_vec', $qVec, 10, 'cosine', {case_id: $matter},
                     {fusion: 'score', weights: {bm25: 0.3, vector: 0.7}})
YIELD node, score, bm25_rank, vec_rank

CALL db.hybridSearch('Fact', 'said', $q, 'text_vec', $qVec, 10, 'cosine', {case_id: $matter},
                     {at_valid: '2026-06-01T00:00:00Z'})
YIELD node, score

A call without these options fuses by RRF as before, with the same scores. A filter or nodeIds at a past time is checked on each node’s version at that time, in the grammar of the gds.vectorSearch filter (no property index is needed for it there), so a node moved to another matter later is found in its old matter; through 1.4.3.2 these were refused with UNSUPPORTED_FEATURE. Such a call reads each node of the label at that time. RRF looks at ranks only, so a weight changes an RRF ranking less than it suggests; with fusion: 'score' how far apart a side’s scores are counts. With index: 'declared', bm25Prop may be a list of properties or a map of property to weight, and the keyword side ranks by the weighted sum, as db.fulltext.query with the same fields. stats.vector_profile.hybrid_fusion_method says how a call fused: rrf, rrf_weighted, score_minmax or score_max. Bad option values are refused with FULLTEXT_OPTION_INVALID.

Inline vector functions

// In WHERE
MATCH (d:Doc) WHERE vector.similarity(d.embedding, $query) > 0.75 RETURN d

// In RETURN
MATCH (d:Doc) RETURN d.title, vector.similarity(d.embedding, $query) AS sim
ORDER BY sim DESC LIMIT 10

// Functions: vector.similarity, vector.distance, vector.dot, vector.norm,
// vector.normalize, vector.dim, vector.equals, vector.zero, vector.slice
// Older names cosine, euclidean, and dotProduct accept lists only
// From 1.4.2.2: vector.similarity.cosine(a, b) = (1 + cos) / 2 and
// vector.similarity.euclidean(a, b) = 1 / (1 + d^2), both in [0, 1] (the Neo4j 5 names);
// vector.similarity is unchanged (the raw cosine)

These functions return an exact score for each row that MATCH and WHERE produce. A WHERE vector.similarity(...) > t filter never uses a vector index. For top-k search over a vector index, use gds.vectorSearch or db.hybridSearch. With ORDER BY vector.similarity(...) DESC LIMIT k and a literal k, only the top k rows are kept while scoring.

Predicate-filtered vector search

Vectors are stored as node properties, so a query can filter nodes with MATCH and WHERE and then rank the remaining rows by similarity.

// Only rank Documents this team owns and that are still active,
// then order the survivors by similarity to the query vector.
MATCH (n:Document)
WHERE n.team = $team AND n.status = 'active'
RETURN n
ORDER BY vector.similarity(n.embedding, $q) DESC
LIMIT 10

WHERE keeps the rows that match the filter, and ORDER BY vector.similarity(...) ranks only those rows. The filter can use labels, properties, and relationships.

This example filters by a relationship:

// Rank only documents authored by someone on the current project
MATCH (p:Person)-[:MEMBER_OF]->(:Project {id: $project})
MATCH (p)-[:AUTHORED]->(n:Document)
RETURN n.title, vector.similarity(n.embedding, $q) AS sim
ORDER BY sim DESC
LIMIT 10

gds.vectorSearch options (from 1.4.3.2: rescore and exact)

// Pre-filter on fields of the searched label: the exact top k among the nodes that pass
CREATE INDEX FOR (n:Article) ON (n.source)
CREATE INDEX FOR (n:Article) ON (n.published)

CALL gds.vectorSearch('Article', 'embedding', $q, 300,
  {filter: {source: $sources, published: {gte: $from, lte: $to}}})
YIELD node, score
RETURN node.id AS id, score

// Only the best 300 rows get exact scores; the rest gather candidates
CALL gds.vectorSearch('Article', 'embedding', $q, 3000, {rescore: 300})
YIELD node, score, exact
RETURN node.id AS id, score, exact

The 5th argument of gds.vectorSearch(label, property, queryVector, k, config) is a map with the keys metric, filter, nodeIds, atValid, atRecorded, strict and, from 1.4.3.2, rescore. An unknown key is refused with ARGUMENT_TYPE_MISMATCH. The columns are nodeId, node, strId, score and, from 1.4.3.2, exact. A CALL without YIELD returns exact only when rescore is given. exact says how a row’s score was computed; it does not make an approximate (HNSW) search exact.

The filter grammar. filter selects the nodes searched before the top k, so no row is lost to filtering after the ranking and the answer is the exact top k among the nodes that pass.

A missing or null value does not pass, nor does a value that cannot be compared with the condition. With atValid / atRecorded the filter is checked on each node’s version at that time. A condition on a property with an index on the searched label is answered from the index; a range is answered from it only when every stored value of the property has the index’s type (a node holding a float or a string under an integer property makes the search read the label instead, with the same answer). Without an index the condition is checked on each node’s record, which reads the label. Declare the indexes on each searched label. nodeIds lists the nodes the search may return (node ids, string ids or nodes, for example the collected result of a MATCH); with a filter, a node must be listed and pass it.

Partial rescoring. With rescore: r below k, over a label whose vectors are kept in a vector file:

• the first r rows are the exact search’s first r rows, with the same nodes, exact scores and order;
• the other k - r rows are the next best rows by their 8-bit score from the vector file’s codes, each with that score and exact false, ordered by that score. They follow the exact rows whatever their scores, and they may differ from the rows the exact search ranks r + 1 to k;
• the result carries the warning VECTOR_PARTIAL_RESCORE, with exact_rows and code_scored_rows in its details;
• a node written since the vector file was last rewritten is scored from its record, so it is exact and comes with the exact rows;
• filter, nodeIds and field read rules apply to every row.

Without rescore, with rescore of at least k, with atValid / atRecorded, and on a label not kept in a vector file (vectors held in memory, or searched through an approximate HNSW index), every row has its exact score: exact is true and there is no warning. rescore must be a non-negative integer (ARGUMENT_TYPE_MISMATCH; null means no key). The pattern form (ORDER BY vector.similarity(…)) and db.hybridSearch do not take it. A search with rescore is refused by servers older than 1.4.3.2 as an unknown key.

What a search reads (from 1.4.3.2). An exact search with a large k over a vector file ranks every row from the codes, then reads the full vectors of a shortlist in batches, best rows first, and stops as soon as no other row can enter the answer; the answers are the same, bit for bit. A filter or nodeIds that keeps a small share of the label is ranked from the codes too. YIELD node reads from each hit’s record only what the statement uses: RETURN node.id, score reads id, while RETURN score, id(node) and elementId(node) read no record when the label index vouches for the hits, and RETURN node reads the whole record. YIELD nodeId, score never reads a record. Under PROFILE the plan shows VectorSearch with VectorCodeScan, VectorRescore and NodeRecordRead, and stats.vector_profile.search gives the rows and bytes read from codes and full vectors, the reads already in memory, the batches, the records read and the time of each phase; its record counts can include reads by statements running at the same moment.

During bulk writes (from 1.4.3.2). A label’s vector file is brought up to date in the background while writes come in. A search that cannot read the recent changes before its time limit waits for the running update when that ends sooner, or is refused at once with the retryable 503 VECTOR_FILE_REWRITE_PENDING (details.reason overlay_over_deadline, or overlay_no_memory_room; retry after Retry-After). It never returns a partial answer, and a statement that has already committed a write is never refused this way.

Narrowing by a pattern (from 1.4.2.2)

// The filter fields stay on the nodes and relationships they describe;
// the node that holds the vector carries none of them
MATCH (p:Project)<-[:PART_OF]-(d:Document)-[t:TAGGED]->(s:Section)
WHERE p.region IN $regions AND p.started >= $from
  AND t.retracted IS NULL
RETURN s.id, vector.similarity(s.embedding, $q) AS score
ORDER BY score DESC NULLS LAST LIMIT 10

A statement of this shape scores only the nodes the pattern reaches, instead of walking the whole pattern and reading the vector of every node it reaches. The rows are the ones the full walk gives: one row per path (use RETURN DISTINCT for one per node), a node is returned when any path through the pattern passes, and the statement reads the current data. Rows with exactly equal scores can come in another order; add a second sort key when that order matters. Changing a filter field does not rewrite a record that holds a vector.

The shape: one MATCH of one path with 1 to 4 relationships, each with a type and one hop; not OPTIONAL, no AT VALID / AT RECORDED, no named path; a WHERE of comparisons, IN lists and IS NULL / IS NOT NULL on properties and constants, combined with AND, OR, XOR, NOT, without function calls; ORDER BY vector.similarity(r.p, $q) DESC as the first sort key, a LIMIT, no SKIP, no aggregate; a cosine vector property stored as 32-bit floats. Any other statement walks the whole pattern and gives the same rows. ORDER BY score DESC sorts a missing similarity first, so when a reached node has no vector the full walk answers; write NULLS LAST or add r.p IS NOT NULL. For a narrowing one MATCH cannot state, pass the nodes to gds.vectorSearch as nodeIds.

How read statements run (from 1.4.3)

From 1.4.3 read statements run on a planned query engine where it plans them, and on the interpreter otherwise; the engine can run the first part of a read and the interpreter the rest. Nothing in a statement chooses the engine. Among the statements the engine does not plan, which run on the interpreter as on 1.4.2.5: statements that write, EXPLAIN ANALYZE and PROFILE, reads with a time clause, UNION, subqueries, and the statements of a credential that a graph’s access policy or a field read rule restricts.

• The same rows. Where both answer, the rows are the same. The rows of a statement without ORDER BY come in no defined order and can come in another order than on 1.4.2.5; add ORDER BY when the order matters.
• Fewer budget refusals. The engine holds fewer rows at once than the interpreter, so some reads that 1.4.2.5 refused with BUDGET_EXCEEDED (row budget) or QUERY_MEMORY_BUDGET now answer.
• Reads of many records. A statement that reads the records of many nodes or relationships (the targets of a hop, a relationship’s properties, the properties a RETURN or WITH uses) reads them together, in id order. A pattern check between two nodes the row already holds, over one or two hops (WHERE (a)-[:KNOWS]->(b)), is answered from the two nodes’ relationships. The answers do not change. Neither applies to a credential that a graph’s access policy restricts.
• ORDER BY of large integers and floats. A sort key that mixes integers above 2⁵³ with floats compares the exact values, on both engines. On 1.4.2.5 the integer was rounded to a float, so the order of such rows could differ between runs or the statement could fail with an internal error.

The query planner (on by default from 1.4.3.2)

From 1.4.3.2 read statements are planned from statistics the server keeps for each graph: the node a pattern starts from and the index it uses, by estimated rows; the order of consecutive MATCH clauses; and from which end a relationship between two bound nodes is checked. The statistics are built in the background after a graph opens; no statement waits for them, and until they are ready the graph plans as on 1.4.3.1. Statements that write are planned as before.

• The same rows. A statement returns the same rows as with the planner off.
• What can change is order. Anything that depends on the order rows are read in, when the statement does not fix it with ORDER BY: the order of rows; which rows a LIMIT without ORDER BY keeps, or which of the rows tied under the ORDER BY keys; the order of a collect() list and so head(), last(), [i] and slices of it; and which of two equal grouping keys (2 and 2.0) names a group.
• What to do. A statement that needs an order says ORDER BY on a unique key, and a statement that collects in order sorts first (WITH n ORDER BY n.ts, n.id RETURN collect(n.id)).

On a self-hosted server the operator can turn the planner off for the whole server or for one graph; see the release notes shipped with the bundle.

properties(), keys() and size()

The reserved names (_valid_from, _valid_to, _txn_from, _txn_to, _version, _txn_nano_offset, _valid_nano_offset, _seq) are read from the version’s time span and are never in properties(x), keys(x) or x {.*}; read them by name (x._valid_from). From 1.4.3.2 this also holds for a record that stored a value under one of these names before the write guards, so properties(x)[k] equals x.k for every key k. A property a field read rule hides from the caller is left out, as in RETURN x.

Paging through a label

MATCH (n:Case) WHERE n.court = $court
RETURN n.id, n.title
ORDER BY n.id SKIP $offset LIMIT 100

MATCH (n:L) RETURN … ORDER BY n.p [DESC] SKIP s LIMIT k, with or without WHERE, with literal or parameter SKIP / LIMIT, returns at every moment the rows that a sort of the whole label returns. Nodes created, deleted, given a new key, or given or stripped of the label are in their place on the page, before and after maintenance and restarts. Paging through a label on a unique key with no writes in between therefore returns every node exactly once. A read at a time cut (AT RECORDED t, AT VALID t, AS OF t) pages the label as it stood at the cut. Sort on a unique key, or add one as a second key (ORDER BY n.date, n.id); rows tied under the sort keys can come in any order, so a page boundary between tied rows is not fixed. Builds before 1.3.10.1 could leave out nodes written since the last maintenance pass from the form without WHERE.

Counts (from 1.4.3.3)

Exact. A count is the number of matches of the MATCH at its time cut after its WHERE: the number of rows the same statement returns with RETURN n in place of the count. count(x) leaves out the rows where x is null; count(DISTINCT x) counts distinct values. Under an access policy only what the caller may read is counted. A count may also be answered from the label and relationship counts or from an index without reading the matches (EXPLAIN shows which); the answer is the same.

Not refused at the row budget. A RETURN whose items are count, sum, avg, min and max (with or without DISTINCT) and grouping keys, after the statement’s last MATCH, is computed as that MATCH produces its rows when it starts from a scan of a label or of the whole graph, with or without WHERE, AT RECORDED, AT VALID or AS OF. The rows are not kept, so the statement is not refused with BUDGET_EXCEEDED however many rows it counts (through 1.4.3.2, such a count that was not answered from the label and relationship counts or an index was refused when it matched more rows than the server’s row budget). What the statement holds still counts against the budget: one row per group, and the rows of the start nodes it reads at once (a few thousand at most). A single start node whose own matches exceed the budget is still refused. A MATCH that starts from an index lookup, an id() lookup or a node bound by an earlier clause builds its rows first, as before, and so do the rows of earlier MATCH clauses.

Still limited by time. The statement’s time limit applies (HTTP 408 QUERY_TIMEOUT). At a time cut, a read that must resolve more of the graph’s history than the server allows is refused with TEMPORAL_READ_LIMIT; name a label where you can, so that only the nodes that ever carried it are read. Relationship counts at a time without a type (MATCH ()-[r]->() AT RECORDED t RETURN count(*)) are much faster from 1.4.3.3.

Counted row by row. collect(), stDev(), percentileCont(), percentileDisc(), an aggregate inside an expression (count(*) + 1, size(collect(x))), an aggregation in a WITH, an OPTIONAL MATCH as the last clause, a shortestPath pattern, EXPLAIN ANALYZE and private-mode keys may keep every row they aggregate, and those rows count against the row budget.

Declared column files (from 1.4.3.3; opt-in)

CALL db.createColumn('node', 'Message', 'creationDate') YIELD state, created
CALL db.createColumn('relationship', 'HAS_MEMBER', 'joinDate') YIELD state
CALL db.listColumns() YIELD kind, name, property, state, rows, skipped
CALL db.dropColumn('node', 'Message', 'creationDate') YIELD dropped

A declared column holds the values of one property of a label or relationship type for every record, in id order. The next full maintenance pass writes a column file for each declared label or type; until then db.listColumns() shows the column as populating, then online. A step that reads only declared properties of many records (a filter, an aggregate, a sort key, a label scan with an inline map) takes them from the file instead of reading each record; a record written since the pass is read from its record. The answers are the same with and without column files. The file stores null, booleans, integers, floats, strings and times; a record whose declared property holds a list, a map, bytes or a vector is read from its record (counted in skipped). created is false when the column was already declared, and dropped is false when none was. Reads stop using a column as soon as it is dropped.

Column files are read only by statements the planned query engine runs, and only for the present: a read at a time cut never uses them. A full maintenance pass with declared columns makes one more pass over the graph’s files. Refused: a kind other than node or relationship, the reserved names (_valid_from, _valid_to, _txn_from, _txn_to, _version, _seq), a property declared for encryption, and read-only servers. Declaring or dropping a column needs a credential that may write to the graph.

Multi-statement transactions (from 1.4.3.2; off by default)

Every Cypher statement is applied all or nothing on its own (see Write statements are all-or-nothing). From 1.4.3.2 a server can also run several statements as one transaction. Transactions are off by default and are not enabled on the hosted service: there, and on any server without them, the routes below answer 404 TRANSACTIONS_DISABLED. A self-hosted operator turns them on with a server setting; see the release notes shipped with the bundle.

POST   /graphs/{name}/tx                begin            -> 201 {"transactionId": "tx_...", ...}
POST   /graphs/{name}/tx/{id}/cypher    run a statement  (body and answer as /graphs/{name}/cypher)
POST   /graphs/{name}/tx/{id}/commit    commit
DELETE /graphs/{name}/tx/{id}           roll back
GET    /graphs/{name}/tx/{id}           status
POST   /graphs/{name}/tx/commit         run {"statements": [...]} as one transaction and commit

• All or nothing. Either every statement’s writes are applied, or none are, also across a crash. The commit answers after the transaction is durable. Every version the transaction writes carries one transaction time (txnTimeMs in the commit answer).
• Isolation. Transactions on one graph run one at a time: a transaction holds the graph’s write lock from its start to its end, so other writes to the graph wait (up to 30 seconds, then 503 WRITE_LOCK_TIMEOUT). Each statement sees the writes of the statements before it; other clients see none of them before the commit. Keep transactions short.
• Failures. Any error answer to a statement rolls the whole transaction back; the answer carries Transaction-Status: rolled_back, and later requests on it answer 404 TXN_NOT_FOUND. There are no savepoints.
• Constraints are checked at the commit, on the final data (409 CONSTRAINT_VIOLATION, nothing applied).
• Retries. Send an Idempotency-Key with the commit; a statement inside a transaction cannot carry one (400 IDEMPOTENCY_KEY_UNSUPPORTED).
• Limits. 30 seconds per transaction by default (timeoutMs when it begins, up to 120 seconds), rolled back after 10 seconds without a statement. Not allowed inside a transaction (400 TXN_STATEMENT_NOT_ALLOWED): index and constraint statements, schema procedures, db.embedBackfill, db.destroySubjectKey and background graph-algorithm writes. One graph per transaction (TXN_CROSS_GRAPH). A write dated before a version the same transaction wrote is refused (TXN_BACKDATED_OWN_WRITE); history reads inside a transaction see its writes only as each entity’s current version. A restart rolls back open transactions.
• MCP. Where transactions are on, the per-graph MCP endpoint lists the tool cypher_transaction, which runs a list of statements as one transaction and commits.

Parameter substitution

// Values only, including SKIP and LIMIT
MATCH (p:Person) WHERE p.role = $role RETURN p LIMIT $page_size

Parameters can stand for values: in WHERE, RETURN, WITH, ORDER BY, SKIP, LIMIT, pattern property values, a whole property map ((n:Person $props)), SET values, UNWIND and FOREACH lists, procedure arguments, and time values. They cannot stand for labels, relationship types, property keys, variable-length bounds such as *1..$n, or index and constraint statements.

EXPLAIN, EXPLAIN ANALYZE, PROFILE, EXPLAIN CHANGE, DIFF GRAPH

EXPLAIN MATCH (n:Person) WHERE n.email = $e RETURN n
// → planner text, no execution

EXPLAIN ANALYZE MATCH (n:Person) WHERE n.email = $e RETURN n
// → runs the query, including any writes, and adds plan_stats (rows and microseconds per operator)

PROFILE MATCH (n:Person) WHERE n.email = $e RETURN n
// → from 1.4.1, the same as EXPLAIN ANALYZE

EXPLAIN CHANGE MATCH (n:Person {email: $e}) RETURN n
// → change history of the matched nodes: seq, txn_at, op_kind, entity_id

DIFF GRAPH FROM '2025-06-01' TO '2025-07-01'
// → history operations recorded in the range

From 1.4.1, PROFILE <statement> is accepted and is the same as EXPLAIN ANALYZE; 1.4 and earlier accept EXPLAIN ANALYZE only. From 1.4.1, EXPLAIN names the index a labelled read without a time clause starts from for WHERE equalities, IN lists and ranges; a read with no usable index prints label scan (or full scan without a label); tests that compare EXPLAIN text can change.

From 1.4.1, the stats of every response also carry rows_materialized (rows counted against the statement’s row budget; a row is counted at each step that builds it, so this can exceed rows_returned), row_budget (the row budget that applied; 0 means none) and nodes_read (node records the MATCH clauses read as start candidates, before WHERE; nodes reached through a relationship are not counted).

Things to watch

Quickstart →  ·  SDK →  ·  MCP tools →  ·  All features →