OriginChainDB docs
docs · graph · embeddings

Graph embeddings.

Two embedding families ship in-engine: Node2Vec (biased random-walk) and GraphSAGE (attribute-aware, neighbour-aggregating, three aggregators). Both persist to disk and install into the vector index so you can run nearest-neighbour search over learned node representations. Both train against a relation you have already declared on the schema, so declare the relation first.

Node2Vec.

Skip-gram over biased random walks. Two knobs decide what the walks explore: p (return likelihood) and q (in-out bias). Low q favors depth-first exploration (structural roles); high q favors breadth-first (homophily).

  • pReturn likelihood. Higher = less revisiting.
  • qIn-out bias. < 1 = depth-first; > 1 = breadth-first.
  • walk_lengthSteps per walk. 20–80 is the usual band.
  • num_walksWalks started per node.
POST /v1/tenants/:t/graph/:t/:rel/embeddings/node2vec/train 
curl -X POST "https://acme.db.originchain.ai/v1/tenants/$T/graph/users/follows/embeddings/node2vec/train" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dim":         128,
    "walk_length": 40,
    "num_walks":   10,
    "p":           1.0,
    "q":           0.5,
    "window":      10
  }'

GraphSAGE.

Attribute-aware. Each layer samples a neighbourhood, transforms each neighbour's representation, then aggregates. Three aggregators ship — pick the one that fits your graph shape.

aggregatorwhen to pickcost
Mean Default. Smooths neighbour attributes by averaging. Fastest aggregator; reasonable accuracy on most homophilous graphs. Cheapest.
MaxPool Element-wise max of a per-neighbour transform. Best representational capacity per parameter; pick when neighbour outliers carry signal. ≈ 2× Mean per training step.
LSTM Sequence-aware aggregation with deterministic per-(node, layer) shuffle so retrains converge to the same vector. Pick when neighbour ordering matters or the graph carries time-like structure. ≈ 5–8× Mean per training step.
POST /v1/tenants/:t/graph/:t/:rel/embeddings/graphsage/train 
curl -X POST "https://acme.db.originchain.ai/v1/tenants/$T/graph/users/follows/embeddings/graphsage/train" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dim":        128,
    "aggregator": "max_pool",       // "mean" | "max_pool" | "lstm"
    "layers":     2,
    "sample_per_layer": [10, 5]
  }'

Persistence + top-k.

Trained embeddings persist to disk. Install them into the vector index via the same install-centroids HTTP admin used for IVF, then the engine treats them as a regular vector collection — topk gives you nearest-neighbour search over node embeddings, filterable by metadata. See docs/vector for the topk surface.