Graph embeddings
Graph embeddings turn a node’s relationships into a list of numbers so you can find similar nodes. Prepare the graph first, train a model, then query the saved representations. Training changes stored data; it is not a read-only query.
- Prepare the graphUse a supported same-schema relation and representative connected records.
- Choose a training methodConfigure the supported Node2Vec or GraphSAGE operation.
- Train and save vectorsInspect the result before using the generated representations.
- Query a known nodeCompare nearby vectors with relationships in the source graph.
Prepare a graph
Complete the graph quickstart. Its graph_demo.people table has a follows relation targeting the same table. Graph embedding training requires this same-schema relation; a cross-table relation is not interchangeable.
Use the same endpoint, tenant and bearer environment variables, with database identity headers when required. The three-node fixture demonstrates the API; meaningful embeddings require a representative graph.
Train Node2Vec
Node2Vec learns which nodes tend to appear near one another in walks through the graph. The example trains on the declared follows relation and saves one numeric representation per node.
curl --fail-with-body -X POST "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/graph_demo.people/node2vec" \
-H "Authorization: Bearer $OC_BEARER" -H "Content-Type: application/json" \
-d '{"rel":"follows","dim":16,"walks_per_node":5,"walk_length":10,"window_size":3,"epochs":1,"seed":42,"persist":true}'Check the status and returned training summary, including dimension and persistence. This request performs training; it is not a job proposal or a read-only operation. Keep training budgets small while evaluating a new graph.
Query persisted embeddings
curl --fail-with-body --get "$OC_BASE_URL/v1/tenants/$OC_TENANT/graph/graph_demo.people/node2vec/follows/topk" \
-H "Authorization: Bearer $OC_BEARER" \
--data-urlencode "query=u1" --data-urlencode "k=3" --data-urlencode "metric=cosine"This graph embedding query names a source node with query. It is different from the vector-table top-k request, which supplies a numeric query vector. Persisted graph embeddings do not require an IVF centroid-installation request.
Use GraphSAGE for node features
GraphSAGE combines the graph’s links with a numeric feature column on each node. Prepare consistent feature dimensions and choose the supported aggregator before training. Follow the complete GraphSAGE request; its parameters differ from Node2Vec.
Refresh deliberately
A later row or edge update does not imply that learned embeddings have been retrained. Track the graph and model version used for a run, refresh when needed and evaluate retrieval quality on representative queries. See Node2Vec options and response formats.