Cypher Graph Queries

Zatabase includes a built-in Cypher query engine for graph traversal and pattern matching. Nodes are stored as rows in labeled tables, and relationships (edges) are first-class objects with types, direction, and properties. This lets you model and query graph structures alongside your relational and vector data — all in one database.

Endpoint

All Cypher queries are executed via:

POST /v1/cypher
Authorization: Bearer <token>
Content-Type: application/json

{"cypher": "YOUR CYPHER QUERY HERE"}

Response Format

{
  "rows": [ ... ],
  "affected": null
}

• rows — Array of JSON objects for read queries (MATCH).
• affected — Number of nodes/relationships created, deleted, or merged for write operations.

Data Model

Zatabase’s graph model maps onto its existing table/row storage:

• Nodes are rows in a table. The table name serves as the node label (e.g., Person, Movie, City).
• Relationships (edges) are directed, typed connections between two nodes. Each edge has a type (e.g., KNOWS, LIKES), a direction, and optional properties stored as key-value pairs.
• Properties on both nodes and edges can be integers, floats, strings, booleans, vectors, lists, or null.

Property Types

Type	Cypher Literal	Example
Integer	bare number	42, -7
Float	decimal number	3.14, 0.5
String	single-quoted	'hello'
Boolean	keyword	true, false
Null	keyword	null
Vector	bracket array	[0.1, 0.2, 0.3] (in ORDER BY distance)

MATCH

MATCH finds patterns in the graph. Every MATCH requires at least one relationship hop.

Basic Pattern Matching

Find all people who know other people:

MATCH (a:Person)-[r:KNOWS]->(b:Person)
RETURN a, b

• (a:Person) — binds variable a to nodes in the Person table.
• -[r:KNOWS]-> — traverses outgoing edges of type KNOWS, binding the relationship to r.
• (b:Person) — binds the target node to b.

curl Example

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN a, b LIMIT 10"}'

Multi-Hop Patterns

Chain multiple hops to traverse deeper into the graph:

MATCH (a:Person)-[r:KNOWS]->(b:Person)-[s:LIKES]->(c:Movie)
RETURN a, c

This finds people who know someone who likes a movie.

Variable-Length Paths

Use *min..max to match paths of variable length:

MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
WHERE a.name = 'Alice'
RETURN b

This finds all people reachable from Alice through 1 to 3 KNOWS hops.

Supported formats:

• *1..3 — between 1 and 3 hops
• *2 — exactly 2 hops
• *1.. — 1 or more hops (no upper bound)
• *..3 — up to 3 hops

OPTIONAL MATCH

OPTIONAL MATCH works like a left outer join: if no matching pattern is found, the unmatched variables are kept as null rather than filtering out the row.

MATCH (p:Person)-[:IN]->(c:City)
OPTIONAL MATCH (p:Person)-[:OWNS]->(pet:Pet)
RETURN p, pet

People without pets still appear in the results; their pet variable will be unbound.

RETURN

The RETURN clause specifies what data to include in the results.

Return Variables

Return entire nodes:

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a, b

Property Access

Return specific properties:

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name, b.name

Aliases

Use AS to rename returned properties:

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name AS source, b.name AS target

Edge Property Access

Access properties on relationships by binding the edge to a variable:

MATCH (a:Person)-[r:KNOWS]->(b:Person)
WHERE r.since > 2020
RETURN a.name, b.name, r.since

Aggregations

Three aggregation functions are supported:

COUNT — count matching rows:

MATCH (p:Person)-[:IN]->(c:City)
RETURN COUNT(*) AS total

MATCH (p:Person)-[:IN]->(c:City)
RETURN COUNT(p) AS people_count

SUM — sum a numeric property:

MATCH (o:Order)-[:FOR]->(c:Customer)
RETURN SUM(o.amount) AS revenue

COLLECT — collect property values into a list:

MATCH (p:Person)-[:IN]->(g:Group)
RETURN COLLECT(p.name) AS members

All aggregation functions support AS aliases.

WHERE

Filter results with WHERE clauses after the MATCH pattern.

Comparison Operators

Operator	Description
=	Equal to
<>	Not equal to
<	Less than
>	Greater than
<=	Less than or equal
>=	Greater than or equal

MATCH (a:Item)-[:HAS]->(t:Tag)
WHERE a.price > 20
RETURN a

Cross-type numeric comparisons work (integer vs. float):

WHERE a.price >= 9.99

Logical Operators

Combine conditions with AND, OR, and NOT:

MATCH (a:N)-[:R]->(b:M)
WHERE a.x = 1 OR a.x = 3
RETURN a

MATCH (a:N)-[:R]->(b:M)
WHERE NOT a.x = 2
RETURN a

MATCH (a:N)-[:R]->(b:M)
WHERE (a.x = 1 OR a.x = 2) AND NOT a.x = 2
RETURN a

Parentheses are supported for grouping.

String Predicates

Predicate	Description
STARTS WITH	String prefix match
ENDS WITH	String suffix match
CONTAINS	Substring match

MATCH (p:Person)-[:LIVES_IN]->(c:City)
WHERE p.name STARTS WITH 'Ali'
RETURN p

WHERE p.name ENDS WITH 'son'

WHERE p.name CONTAINS 'li'

NULL Checks

WHERE a.email IS NULL
WHERE a.email IS NOT NULL

Property-to-Property Comparison

Compare properties across nodes or edges:

MATCH (a:Item)-[:RELATED]->(b:Item)
WHERE a.price > b.price
RETURN a, b

ORDER BY and LIMIT

LIMIT

Restrict the number of returned rows:

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a, b
LIMIT 10

ORDER BY distance()

Order results by vector similarity using the distance() function. This enables graph + vector hybrid queries — a unique Zatabase capability.

MATCH (a:docs)-[:similar]->(b:docs)
WHERE a.title = 'Introduction'
RETURN b
ORDER BY distance(b.embedding, [0.1, 0.2, 0.3], 'l2')
LIMIT 5

The distance() function takes three arguments:

1. A property reference to a vector field (e.g., b.embedding)
2. A query vector as a bracket-delimited array
3. A distance metric as a string

Supported distance metrics:

Metric	String	Description
L2 (Euclidean)	'l2'	Euclidean distance (default)
Cosine	'cosine'	Cosine distance (1 - cosine similarity)
Dot Product	'dot', 'inner', 'innerproduct'	Negated dot product (for distance ordering)

This is how you combine graph traversal with vector search — traverse relationships to find related nodes, then rank them by embedding similarity.

CREATE

Create new nodes and relationships.

Create a Node

CREATE (a:Person {name: 'Alice', age: 30})

This inserts a row into the Person table with the specified properties. The table is created automatically if it doesn’t exist.

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "CREATE (a:Person {name: '\''Alice'\'', age: 30})"}'

Create Multiple Nodes

CREATE (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})

Create a Relationship

Create a relationship between two nodes defined in the same statement:

CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})

Relationships can also carry properties:

CREATE (a:Person {name: 'Alice'})-[:KNOWS {since: 2020}]->(b:Person {name: 'Bob'})

MERGE

MERGE is an idempotent create: it finds a matching node or creates one if none exists. This is useful for ensuring data is not duplicated.

MERGE (a:Person {name: 'Alice'})

• If a node with label Person and name = 'Alice' exists, it returns the existing node.
• If no match is found, it creates a new node with those properties.

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MERGE (a:Person {name: '\''Alice'\''})"}'

Note: ON MATCH SET / ON CREATE SET clauses are not yet supported. MERGE for relationships requires using a MATCH + CREATE pattern instead.

DELETE

Delete nodes and relationships found by a MATCH pattern.

Delete a Node

MATCH (a:Person)-[:TAGGED]->(t:Tag)
WHERE a.name = 'Alice'
DELETE a

DETACH DELETE

DETACH DELETE removes the node and all its incoming and outgoing edges:

MATCH (a:Person)-[:TAGGED]->(t:Tag)
WHERE a.name = 'Alice'
DETACH DELETE a

Delete a Relationship

Delete just the relationship by binding it to a variable:

MATCH (a:Person)-[r:KNOWS]->(b:Person)
WHERE a.name = 'Alice' AND b.name = 'Bob'
DELETE r

Delete Multiple Targets

MATCH (a:Person)-[r:KNOWS]->(b:Person)
WHERE a.name = 'Alice'
DELETE a, r

PG Wire Protocol Access

Cypher queries can also be executed through the PostgreSQL wire protocol using special function syntax. Zatabase registers Cypher-related functions accessible from any PostgreSQL client:

Function	Description
cypher_query(query, params)	Execute a Cypher query with parameters
cypher_match(pattern, where, return)	Execute a MATCH query
cypher_create(pattern, properties)	Execute a CREATE
cypher_merge(pattern, properties)	Execute a MERGE
cypher_delete(match, detach)	Execute a DELETE
cypher_path(start, end, max_depth)	Find a path between nodes
cypher_shortest_path(start, end)	Find shortest path

Graph analysis functions are also available:

Function	Description
graph_degree(node, direction)	Get node degree
graph_neighbors(node, direction)	Get neighboring nodes
graph_components(type)	Find connected components
graph_centrality(type, nodes)	Compute centrality metrics

psql "postgresql://admin:[email protected]/zatabase" -c \
  "SELECT * FROM cypher_query('MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a, b', '{}')"

Comparison with Neo4j

Zatabase’s Cypher implementation covers the core subset of Neo4j’s Cypher query language while adding unique capabilities like vector similarity search within graph traversals.

What’s the Same

Feature	Zatabase	Neo4j
MATCH with pattern matching	Yes	Yes
OPTIONAL MATCH	Yes	Yes
Node labels and relationship types	Yes	Yes
Property access (n.name)	Yes	Yes
WHERE with comparisons	Yes	Yes
AND / OR / NOT	Yes	Yes
String predicates (STARTS WITH, ENDS WITH, CONTAINS)	Yes	Yes
IS NULL / IS NOT NULL	Yes	Yes
Variable-length paths (*1..3)	Yes	Yes
CREATE nodes and relationships	Yes	Yes
MERGE (idempotent create)	Yes	Yes
DELETE / DETACH DELETE	Yes	Yes
RETURN with property access and aliases	Yes	Yes
COUNT, SUM, COLLECT aggregations	Yes	Yes
ORDER BY and LIMIT	Yes	Yes
Edge properties	Yes	Yes
Multi-hop patterns	Yes	Yes
Inline property constraints {name: 'Alice'}	Yes	Yes

What’s Different

Feature	Zatabase	Neo4j
ORDER BY distance() for vector search	Yes	No
Runs alongside SQL and vector search	Yes	No (separate database)
ON MATCH SET / ON CREATE SET in MERGE	Not yet	Yes
SET clause for property updates	Not yet	Yes
WITH clause for query chaining	Not yet	Yes
UNWIND clause	Not yet	Yes
GROUP BY	Not yet	Yes
CASE expressions	Not yet	Yes
WHERE ... IN [list]	Not yet	Yes
Multiple labels per node	Not yet	Yes
Index hints	Not yet	Yes
FOREACH	Not yet	Yes
CALL procedures	Not yet	Yes
Path functions (length(), nodes(), relationships())	Not yet	Yes

Zatabase-Unique Features

• Graph + Vector hybrid queries: Traverse graph patterns then rank results by vector similarity using ORDER BY distance(). No other graph database offers this natively.
• Unified engine: Graph queries, SQL queries, and vector search all operate on the same underlying data — no data duplication or sync required.
• Permission-aware traversal: Graph queries respect Zatabase’s RBAC permission system. Row-level and table-level deny rules are enforced during traversal.
• Persistent edges: Edges are automatically persisted to the ZQL storage engine and survive server restarts.

Complete Examples

Social Network: Find Friends of Friends

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (me:Person)-[:KNOWS*1..2]->(friend:Person) WHERE me.name = '\''Alice'\'' RETURN friend.name"}'

Knowledge Graph: Traverse and Rank by Similarity

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (a:Document)-[:RELATED]->(b:Document) WHERE a.title = '\''Introduction'\'' RETURN b ORDER BY distance(b.embedding, [0.1, 0.2, 0.3, 0.4], '\''cosine'\'') LIMIT 5"}'

E-Commerce: Sum Order Values

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (o:Order)-[:FOR]->(c:Customer) WHERE c.name = '\''Acme'\'' RETURN SUM(o.amount) AS revenue"}'

Idempotent Node Creation

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MERGE (u:User {email: '\''[email protected]'\'', name: '\''Alice'\''})"}'

Delete with Relationship Cleanup

curl -s -X POST https://your-project.zatabase.io/v1/cypher \
  -H "Authorization: Bearer $ZATABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (a:Person)-[:KNOWS]->(b:Person) WHERE a.name = '\''Alice'\'' DETACH DELETE a"}'

Limitations

• MATCH requires at least one relationship hop. You cannot MATCH (a:Person) RETURN a — a relationship pattern is required. Use the SQL endpoint for simple table scans.
• MERGE for relationships is not supported directly. Use MATCH to find existing nodes, then CREATE the relationship via the API.
• ON MATCH SET / ON CREATE SET clauses in MERGE are not yet implemented.
• SET, REMOVE, WITH, UNWIND, FOREACH, CALL are not yet supported.
• Multiple labels per node are not supported. Each node has exactly one label (its table name).
• No CREATE INDEX — indexes are managed through Zatabase’s SQL interface or API.
• Relationship creation in the HTTP handler currently only supports creating nodes via CREATE. Full relationship creation through the Cypher endpoint requires the relationship patterns to reference variables bound in the same CREATE statement.

Best Practices

1. Always specify node labels. Unlabeled source nodes require prior variable binding, which is not possible in a single-statement query. Labels also constrain the scan to a single table, improving performance.

2. Use LIMIT on large graphs. Without a limit, MATCH will return all matching patterns, which can be expensive on large datasets. The default server-side cap is 1000 rows.

3. Prefer MERGE for idempotent writes. When ingesting data that may overlap, MERGE prevents duplicate nodes.

4. Use DETACH DELETE for nodes with edges. Plain DELETE on a node that has edges will remove the node but the dangling edge references are also cleaned up. Use DETACH DELETE for clarity and to explicitly remove all connected edges.

5. Combine graph + vector for semantic search. Zatabase’s unique strength is hybrid queries: traverse a knowledge graph to find candidate nodes, then rank them by embedding similarity using ORDER BY distance().

6. Use edge properties for weighted graphs. Relationship properties (e.g., {weight: 0.8, since: 2020}) are accessible in WHERE and RETURN clauses, enabling weighted graph algorithms.

7. Keep variable-length paths bounded. Open-ended paths (*1..) can be expensive. Set a reasonable max_hops (e.g., *1..5) to avoid unbounded exploration.