GraphService
Core graph CRUD operations.
Proto source
Transport
All methods are available via:
- gRPC on port 7080 — native high-performance API
- REST/JSON on port 7081 — HTTP/JSON transcoding via embedded structured-proxy
Methods
CreateNode
Create a new node with the given labels and properties.
HTTP: POST /v1/graph/nodes
Request: CreateNodeRequest
| Field | Type | Description |
|---|---|---|
labels | string[] | — |
properties | map<string, PropertyValue> | — |
Response: Node
| Field | Type | Description |
|---|---|---|
node_id | uint64 | Raw 64-bit node identifier. Preserved for Neo4j v4 driver compatibility and direct internal addressing. New client code SHOULD prefer element_id. |
labels | string[] | — |
properties | map<string, PropertyValue> | — |
element_id | string | Canonical opaque identifier: 13-character Crockford base32 encoding of node_id (bijective). Stable across schema changes, restarts, replication. Use this as the primary node reference in application code per ADR-022. |
CreateNodesBatch
Create N nodes in a single transaction. Server batches secondary index updates (HNSW graph builds, full-text posting list appends, B-tree entries) so a bulk load of M nodes carrying vector or text properties costs one index write per index, not M. The whole batch is atomic: either every node is created or none are. Created nodes are returned in input order.
HTTP: POST /v1/graph/nodes:batch
Request: CreateNodesBatchRequest
| Field | Type | Description |
|---|---|---|
nodes | CreateNodeRequest[] | Nodes to create, in caller-defined order. Each entry has the same semantics as a single CreateNodeRequest. Server returns the created nodes in the same order via CreateNodesBatchResponse.nodes. An empty list is a valid no-op and returns an empty response. |
Response: CreateNodesBatchResponse
| Field | Type | Description |
|---|---|---|
nodes | Node[] | Created nodes, in the same order as CreateNodesBatchRequest.nodes. Length matches the request's nodes length on success. |
GetNode
Get a node by its ID.
HTTP: GET /v1/graph/nodes/{node_id}
Request: GetNodeRequest
| Field | Type | Description |
|---|---|---|
node_id | uint64 | — |
Response: Node
| Field | Type | Description |
|---|---|---|
node_id | uint64 | Raw 64-bit node identifier. Preserved for Neo4j v4 driver compatibility and direct internal addressing. New client code SHOULD prefer element_id. |
labels | string[] | — |
properties | map<string, PropertyValue> | — |
element_id | string | Canonical opaque identifier: 13-character Crockford base32 encoding of node_id (bijective). Stable across schema changes, restarts, replication. Use this as the primary node reference in application code per ADR-022. |
CreateEdge
Create an edge between two nodes.
HTTP: POST /v1/graph/edges
Request: CreateEdgeRequest
| Field | Type | Description |
|---|---|---|
edge_type | string | — |
source_node_id | uint64 | — |
target_node_id | uint64 | — |
properties | map<string, PropertyValue> | — |
Response: Edge
| Field | Type | Description |
|---|---|---|
edge_id | uint64 | — |
edge_type | string | — |
source_node_id | uint64 | — |
target_node_id | uint64 | — |
properties | map<string, PropertyValue> | — |
element_id | string | Canonical opaque identifier for the edge endpoints (concatenated source and target element_ids in canonical order). Edges in CoordiNode are typed property bags between two nodes, not first-class entities — this field exists for parity with Neo4j relationships, not as a stable handle. |
Traverse
Traverse edges from a starting node.
HTTP: POST /v1/graph/traverse
Request: TraverseRequest
| Field | Type | Description |
|---|---|---|
start_node_id | uint64 | — |
edge_type | string | — |
direction | TraversalDirection | OUTBOUND, INBOUND, or BOTH. |
max_depth | uint32 | — |
pagination | PaginationRequest | — |
Response: TraverseResponse
| Field | Type | Description |
|---|---|---|
nodes | Node[] | — |
edges | Edge[] | — |
pagination | PaginationResponse | — |
Types
CreateEdgeRequest
| Field | Type | Description |
|---|---|---|
edge_type | string | — |
source_node_id | uint64 | — |
target_node_id | uint64 | — |
properties | map<string, PropertyValue> | — |
CreateNodeRequest
| Field | Type | Description |
|---|---|---|
labels | string[] | — |
properties | map<string, PropertyValue> | — |
CreateNodesBatchRequest
Bulk-create N nodes in one transaction. Same shape as N back-to-back CreateNode calls, but processed under a single server-side lock acquisition with deferred secondary-index commit at the end of the batch — primary win for vector-heavy bulk loads (HNSW write lock is taken once per batch, not once per node).
| Field | Type | Description |
|---|---|---|
nodes | CreateNodeRequest[] | Nodes to create, in caller-defined order. Each entry has the same semantics as a single CreateNodeRequest. Server returns the created nodes in the same order via CreateNodesBatchResponse.nodes. An empty list is a valid no-op and returns an empty response. |
CreateNodesBatchResponse
| Field | Type | Description |
|---|---|---|
nodes | Node[] | Created nodes, in the same order as CreateNodesBatchRequest.nodes. Length matches the request's nodes length on success. |
GetNodeRequest
| Field | Type | Description |
|---|---|---|
node_id | uint64 | — |
TraverseRequest
| Field | Type | Description |
|---|---|---|
start_node_id | uint64 | — |
edge_type | string | — |
direction | TraversalDirection | OUTBOUND, INBOUND, or BOTH. |
max_depth | uint32 | — |
pagination | PaginationRequest | — |
TraverseResponse
| Field | Type | Description |
|---|---|---|
nodes | Node[] | — |
edges | Edge[] | — |
pagination | PaginationResponse | — |
Enums
TraversalDirection
| Value | Number | Description |
|---|---|---|
TRAVERSAL_DIRECTION_UNSPECIFIED | 0 | — |
TRAVERSAL_DIRECTION_OUTBOUND | 1 | — |
TRAVERSAL_DIRECTION_INBOUND | 2 | — |
TRAVERSAL_DIRECTION_BOTH | 3 | — |