Run your first graph traversal

Create three people connected by a follows relationship. Then read one neighbor and follow two links. A hop means crossing one relationship from one record to the next.

Check a small graph by handThe example includes a cycle; bounded traversal keeps the result small enough to verify.

Declare the follows relationUse the node IDs as source and target keys.
Load u1, u2 and u3Connect them in the cycle shown in the example.
Start at u1Traverse follows with a maximum depth of two.
Inspect each depthCheck u2 at one hop and u3 at two hops.

1. Connect

Use a Bash-compatible terminal and an instance token with schema and row-write permission. The example uses a new graph_demo.people table. If your instance requires database-user identity, add the two identity headers to every request.

export OC_BASE_URL="https://YOUR_INSTANCE_HOST"
export OC_TENANT="YOUR_TENANT_ID"
# Load OC_BEARER from your secret manager.
: "${OC_BEARER:?Set OC_BEARER first}"

2. Declare the relation

Each person has a follows_id naming another person in the same table. This small example has one outgoing link per row. For multiple links, define a supported relation shape. A separate edge table is not traversable without relation declarations; a single string column does not store a list.

curl --fail-with-body -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/schemas" \
  -H "Authorization: Bearer $OC_BEARER" -H "Content-Type: text/plain" \
  --data-binary @- <<'TOML'
namespace = "graph_demo"
table = "people"
primary_key = ["id"]

[[columns]]
name = "id"
ty = "str"
required = true

[[columns]]
name = "follows_id"
ty = "str"

[[relations]]
name = "follows"
from_col = "follows_id"
bidirectional = true
[relations.target]
namespace = "graph_demo"
table = "people"
pk = "id"
TOML

3. Add the records

The data forms a cycle: u1 → u2 → u3 → u1. The relation indexes are maintained as rows are written.

for row in '{"id":"u1","follows_id":"u2"}' '{"id":"u2","follows_id":"u3"}' '{"id":"u3","follows_id":"u1"}'; do
  curl --fail-with-body -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/rows/graph_demo.people" \
    -H "Authorization: Bearer $OC_BEARER" -H "Content-Type: application/json" \
    -d "$row" || break
done

4. Find one neighbor

curl --fail-with-body --get "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/graph_demo.people/neighbors" \
  -H "Authorization: Bearer $OC_BEARER" \
  --data-urlencode "rel=follows" \
  --data-urlencode "pk=u1"

The result contains u2. Use pk for the starting primary key; from is not this endpoint’s parameter.

5. Walk more than one hop

curl --fail-with-body --get "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/graph_demo.people/bfs" \
  -H "Authorization: Bearer $OC_BEARER" \
  --data-urlencode "rel=follows" \
  --data-urlencode "pk=u1" \
  --data-urlencode "max_depth=2"

The traversal reaches u2 at depth 1 and u3 at depth 2. The depth limit is max_depth. A /path request uses src and dst to check reachability; use the algorithm reference when you need a path or cost.

Add a relation to existing data

The console can configure edge-table mappings. The SQL workflow ALTER TABLE … ADD RELATIONSHIP … REFERENCES … can backfill a relation and maintain it on later writes. It currently requires a single-column primary key on the target, and dropping a relationship is not available. See the graph reference and release notes.

Next: algorithm examples, graph schemas or Cypher.

1. ConnectCopy Anchor Link

2. Declare the relationCopy Anchor Link

3. Add the recordsCopy Anchor Link

4. Find one neighborCopy Anchor Link

5. Walk more than one hopCopy Anchor Link