Prepare a graph for Cypher
Define the links that a graph query will follow.
A Cypher query follows the links declared between records.
- Prepare orders and customersUse stable IDs and the expected table indexes.
- Declare the placed_by relationConnect the order’s customer key to the customer table.
- Match from a known orderFollow the declared relation in the query.
- Inspect the customer resultCompare the returned ID with the order’s customer key.
Set up the two tables
- Register
shop.customersfirst. This is the table the order points to. - Add a
customercolumn toshop.orderscontaining the customer's ID. - Name that link
placed_byin a[[relations]]block. - Check that the starting table has a
by_idindex. The schema loader normally creates this for a single-columnidprimary key when no equivalent index exists.
| Schema setting | What it does |
|---|---|
from_col = "customer" | Reads the customer ID from the order. |
target | Identifies the destination table and its key. |
name = "placed_by" | Gives the relationship a name to use in a query. |
bidirectional = true | Also records the reverse direction. |
Customer table example
namespace = "shop"
table = "customers"
primary_key = ["id"]
[[columns]]
name = "id"
ty = "str"
required = true
[[columns]]
name = "name"
ty = "str"
[[columns]]
name = "country"
ty = "str"
[[columns]]
name = "referred_by"
ty = "str" # another customer's id - or absent
# A customer points at the customer who referred them. Source and target
# are the SAME table, which is what makes variable-length paths legal.
[[relations]]
name = "referrer"
from_col = "referred_by"
target = { namespace = "shop", table = "customers", pk = "id" }
bidirectional = true
# Explicit starting-point index; normally synthesized when no equivalent exists.
[[indexes]]
name = "by_id"
columns = ["id"]Order table example
namespace = "shop"
table = "orders"
primary_key = ["id"]
[[columns]]
name = "id"
ty = "str"
required = true
[[columns]]
name = "customer"
ty = "str" # a shop.customers id
[[columns]]
name = "amount_cents"
ty = "i64"
[[columns]]
name = "status"
ty = "str"
[[columns]]
name = "notes"
ty = "str"
[[columns]]
name = "placed_ms"
ty = "u64"
# The edge: an order points at the customer who placed it.
[[relations]]
name = "placed_by"
from_col = "customer"
target = { namespace = "shop", table = "customers", pk = "id" }
bidirectional = true
[[indexes]]
name = "by_id"
columns = ["id"]Check the starting point
A point match such as MATCH (o:orders {id: "…"}) uses an index named by_<primary key column>. For a single-column key, the schema loader adds that index when no equivalent index exists. If you already declared the same key index under another name, check the stored definition: the loader avoids adding a duplicate, while this query path expects the conventional name. The examples declare by_id explicitly.
When you save an order, the relation is maintained from its customer value. You do not need a separate edge-write request.
Run the query
The engine route is POST /v1/tenants/:t/cypher. Send cypher and, when needed, default_schema and params in the request body. Check the supported query shapes before adapting syntax from another graph database.
- Graph modelling: understand relations and their limits.
- Graph examples: build and run a supported traversal.
- SQL: use filters, joins and grouped calculations.