Sample a route through the graph

← Graph examples

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

A random walk chooses one neighbor at each step. It samples local structure without listing all possible routes.

Before you run it: The step cap is 1000. Repeatability requires the same seed and unchanged graph.

First load the five-person social graph. It creates the exact social.users table and follows relation used below.

The sample starts at Alice and can finish early at Erin because Erin has no outgoing links. A repeated node is allowed; this is a sampled walk, not a route that must avoid repeats.

Follow the exampleCopy Anchor Link

1. Choose a relationship and starting key.
2. Set a step limit and explicit seed.
3. Use p and q of 1 for an unbiased walk.
4. Inspect the visited keys.

Set up the relationshipCopy Anchor Link

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

Run the requestCopy Anchor Link

rel, start, steps and seed are required. steps is capped at 1000. The optional p and q values bias the walk; p=1 and q=1 produce the unbiased behavior.

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"

Check the resultCopy Anchor Link

The walk includes its start, can repeat nodes and stops at a dead end.

{
  "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.

Understand the behaviorCopy Anchor Link

• 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.

Important limits and checksCopy Anchor Link

• Omitting seed. It is a required parameter, not an optional one, and the request is rejected without it.
• Assuming the walk has steps plus one entries. It stops early at a dead end. Read the length rather than trusting it.
• Reading a repeated node as a bug. A walk is not a path. It revisits nodes freely, and a two-cycle will bounce between the same pair.
• Drawing conclusions from one walk. A single seeded walk is one draw from a distribution. Aggregate many walks across many seeds before you believe a pattern.

ContinueCopy Anchor Link

Continue to find nodes with similar graph roles.