examples · graph · 1 / 7

1. neighbors - one-hop forward adjacency

what this does

Walks one hop forward along a declared relation. Given the primary key of a source row, returns the array of primary keys it points at. This is the fastest graph query on the substrate - a direct adjacency-list lookup, not a scan.

when to use it

"What products did this order buy?" - one hop, forward direction.
Anywhere you would write SELECT * FROM ... WHERE fk = ? just to follow a foreign key.
As the inner loop of your own traversal when you want hop-by-hop control on the client.

schema requirement

The schema for shop.orders must declare a [[relations]] block with name = "bought_product". See schemas/reference#relations. Without it, the engine returns 404.

the request

GET /v1/tenants/:t/graph/:schema/neighbors?rel=...&pk=...

curl "https://$OC_HOST/v1/tenants/$OC_TENANT/graph/shop.orders/neighbors?rel=bought_product&pk=o001" \
  -H "Authorization: Bearer $OC_TOKEN"

result = db.graph.neighbors(
    "shop.orders",
    rel="bought_product",
    pk="o001",
)

const result = await db.graph.neighbors("shop.orders", {
  rel: "bought_product",
  pk: "o001",
});

result, _ := db.Graph().Neighbors(ctx, "shop.orders", originchain.NeighborsRequest{
    Rel: "bought_product",
    PK:  "o001",
})

what you get back

[
  "p001",
  "p014",
  "p027"
]

A flat array of target primary keys. Order is the insertion order of the edges; do not rely on it being sorted.

how it works

Adjacency is laid down at write time, keyed by (tenant, relation, source_pk).
The read is a single point lookup against that key - no scan, no join.
Cost is independent of total table size; it scales only with the fan-out of this one row.

common mistakes

Relation not declared. Adding a foreign-key column isn't enough - the relation must be in the schema's [[relations]] table.
Wrong direction. neighbors is forward only. For "who points at this row?", use reverse.