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> | — |
operation | OperationRef | The client operation this creation carries out: the node is created at most once however the call is retried, and a retry of a creation that already took effect creates nothing and is refused with FAILED_PRECONDITION, reason OPERATION_SETTLED, naming its outcome. Absent creates unbound. On an entry of CreateNodesBatchRequest it is refused with INVALID_ARGUMENT: the batch names its operation. |
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. |
version | uint64 | The version of this node: the HLC timestamp of the commit that last wrote it. This is the value a conditional write is stated against (CommitTransactionRequest.expect), and it is the same number a write receipt returns as commit_ts, so a read and a later write speak of one thing rather than two. Zero means the server did not resolve a version for this node, not that the node is at version zero: a node that exists always has the commit that wrote it. |
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. |
operation | OperationRef | The client operation the whole batch carries out: the batch takes effect at most once however the call is retried; see CreateNodeRequest.operation. |
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. |
version | uint64 | The version of this node: the HLC timestamp of the commit that last wrote it. This is the value a conditional write is stated against (CommitTransactionRequest.expect), and it is the same number a write receipt returns as commit_ts, so a read and a later write speak of one thing rather than two. Zero means the server did not resolve a version for this node, not that the node is at version zero: a node that exists always has the commit that wrote it. |
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> | — |
operation | OperationRef | The client operation this creation carries out: the edge is created at most once however the call is retried; see CreateNodeRequest.operation. |
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> | — |
operation | OperationRef | The client operation this creation carries out: the edge is created at most once however the call is retried; see CreateNodeRequest.operation. |
CreateNodeRequest
| Field | Type | Description |
|---|---|---|
labels | string[] | — |
properties | map<string, PropertyValue> | — |
operation | OperationRef | The client operation this creation carries out: the node is created at most once however the call is retried, and a retry of a creation that already took effect creates nothing and is refused with FAILED_PRECONDITION, reason OPERATION_SETTLED, naming its outcome. Absent creates unbound. On an entry of CreateNodesBatchRequest it is refused with INVALID_ARGUMENT: the batch names its operation. |
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. |
operation | OperationRef | The client operation the whole batch carries out: the batch takes effect at most once however the call is retried; see CreateNodeRequest.operation. |
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 | — |
OperationRef
A reference to one client operation: what a client persists before sending a write and sends again with every retry of it, on any connection and to any member.
| Field | Type | Description |
|---|---|---|
issuer | bytes | The logical client: 16 bytes the client chooses once and keeps across its restarts (a random value, or a digest of a stable application identity). Independent clients use different issuers; a connection, session or server is not an issuer. |
incarnation | uint64 | The issuer's incarnation the number belongs to, from EnrollIssuerResponse. |
sequence | uint64 | The operation's number within the incarnation, allocated by the client: starting at EnrollIssuerResponse.next_sequence, each new write takes the next number, and a retry of a write keeps its number. Numbers are an identity, not an execution order: writes with different numbers may run concurrently and complete in any order. |
deployment | bytes | The deployment that enrolled the incarnation, 16 bytes, from EnrollIssuerResponse.deployment. A server of another deployment refuses the reference with INVALID_ARGUMENT, reason FOREIGN_OPERATION, rather than admit it as a new operation. |
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 | — |