15. random-walk - seeded and node2vec-biased walks

what this does

random-walk takes a starting node and walks the relation forward for up to steps hops, returning the sequence of primary keys it visited. The walk is deterministic: the same seed on the same graph produces the same walk, byte for byte. Passing p or q switches to the node2vec-biased walk, which is the same sampler the embedding endpoints use internally.

when to use it

• Sampling a large graph cheaply. A few thousand walks give a usable picture without touching every node.
• Generating training sequences for your own embedding or sequence model, outside the engine's built-in node2vec.
• Reproducible exploration. A seeded walk is something you can paste into a bug report and have someone else replay exactly.

schema requirement

The relation must be declared in the schema's [[relations]] block. See schemas/reference#relations.

the request

rel, start, steps and seed are all required - there is no default seed, because a walk you cannot reproduce is not much use. steps is capped at 1000. p (the return parameter) and q (the in-out parameter) are the node2vec bias knobs; setting either one routes the request through the biased walk, and p=1 with q=1 is indistinguishable from the unbiased walk.

curl -G "https://$OC_HOST/v1/tenants/$OC_TENANT/graph/social.users/random-walk" \
  --data-urlencode "rel=follows" \
  --data-urlencode "start=alice" \
  --data-urlencode "steps=5" \
  --data-urlencode "seed=42" \
  -H "Authorization: Bearer $OC_TOKEN"

walk = db.graph.random_walk(
    "social.users",
    start="alice",
    rel="follows",
    steps=5,
    seed=42,
)
# The SDK returns just the walk list:
#   ["alice", "carol", "dave", "erin", "dave", "erin"]

// The TypeScript SDK does not wrap the graph algorithms - use fetch.
const qs = new URLSearchParams({
  rel: "follows",
  start: "alice",
  steps: "5",
  seed: "42",
});
const res = await fetch(
  `https://${OC_HOST}/v1/tenants/${OC_TENANT}/graph/social.users/random-walk?${qs}`,
  { headers: { Authorization: `Bearer ${OC_TOKEN}` } },
);
const { start, walk } = await res.json();

// The Go SDK does not wrap the graph algorithms - use net/http.
url := "https://" + OC_HOST + "/v1/tenants/" + OC_TENANT +
    "/graph/social.users/random-walk?rel=follows&start=alice&steps=5&seed=42"

req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
req.Header.Set("Authorization", "Bearer "+OC_TOKEN)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var out struct {
    Start string   `json:"start"`
    Walk  []string `json:"walk"`
}
json.NewDecoder(resp.Body).Decode(&out)

what you get back

{
  "start": "alice",
  "walk": ["alice", "carol", "dave", "erin", "dave", "erin"]
}

walk begins with the start node, so its length is at most steps plus one. It can be shorter: the walk stops as soon as it reaches a node with no outbound edges. A dead-end start returns a walk containing only that node, and a node with a self-loop walks in place.

how it works

• At each hop the walker picks uniformly among the current node's outbound edges on rel, driven by a seeded generator.
• The same graph, start, step count and seed always produce the same body, so two identical calls are byte-identical on the wire.
• With p or q present the walk becomes second-order: p controls how likely it is to step straight back where it came from, and q how likely it is to move away from the previous node's neighbourhood. Setting both to 1 reduces to the uniform walk by construction.
• steps above 1000 is refused with a 400 quoting the cap, and p=0 is refused because a zero return parameter is not a valid bias.