Find the best few routes

← Graph examples

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

Return up to k routes ordered by cost when an application needs alternatives rather than one distance.

Before you run it: k is required and cannot exceed 50. Weight and endpoint rules are listed below.

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

In the sample dataset, Alice reaches Erin through Bob or Carol, then Dave. With no weight column, cost counts links. The response may contain fewer than three routes even though the request asks for three.

Follow the exampleCopy Anchor Link

1. Prepare the relationship.
2. Use source and target as the endpoint parameters.
3. Set k and optional weight_col.
4. Read the ordered paths and costs.

Set up the relationshipCopy Anchor Link

The relation must be declared in the schema's [[relations]] block. If you pass weight_col, the relation's target table must also declare that column. See schemas/reference#relations.

Run the requestCopy Anchor Link

This endpoint names its endpoints source and target, not src and dst the way path, dijkstra and all_simple_paths do. k is required and is capped at 50; asking for more is a 400 rather than a silent truncation. By default every edge weighs 1, so the ranking is by hop count - pass weight_col to read each edge's weight from a named column on the destination row instead.

curl -G "https://$OC_HOST/v1/tenants/$OC_TENANT/graph/social.users/k-shortest" \
  --data-urlencode "rel=follows" \
  --data-urlencode "source=alice" \
  --data-urlencode "target=erin" \
  --data-urlencode "k=3" \
  -H "Authorization: Bearer $OC_TOKEN"

Check the resultCopy Anchor Link

Unreachable targets return an empty list. Returned paths contain their nodes and costs.

{
  "paths": [
    { "nodes": ["alice", "carol", "dave", "erin"], "cost": 3.0 },
    { "nodes": ["alice", "bob", "carol", "dave", "erin"], "cost": 4.0 }
  ]
}

An object with a paths array, one entry per route, ascending by cost. nodes is the walk in order as plain strings, including both endpoints. Fewer than k entries simply means the graph has no more loop-free routes. An unreachable target is a 200 with "paths": [], not a 404, and a source equal to target comes back as a single zero-cost path.

Understand the behaviorCopy Anchor Link

• Yen's algorithm finds the shortest path, then repeatedly forces a deviation at each node along it and keeps the cheapest result it has not already emitted.
• Routes are loop-free by construction: no node repeats inside a single path.
• With no weight_col every edge weighs 1, so the ranking is by hop count and matches what a breadth-first search would find.
• With weight_col set, each edge's weight is read from that column on the destination row and coerced to a float. The relation has to exist on the schema for that lookup, and an unknown relation name is a 400.
• k above 50 is rejected with the ceiling quoted in the message, so callers learn to budget instead of silently receiving a truncated list.

Important limits and checksCopy Anchor Link

• Sending src and dst. They are source and target on this endpoint. The names differ from the other path endpoints, and the wrong name is a rejected request.
• Treating an empty paths array as an error. Unreachable is a normal 200. Check the array length, not the status code.
• Expecting cost to mean hops once weight_col is set. With weights coming from a column, cost is the sum of those column values and carries whatever units that column has.
• Asking for a large k just in case. Above 50 the whole request is refused, so you get nothing rather than the first fifty.

ContinueCopy Anchor Link

Continue to find the lowest path cost.