gRPC API

Traverse provides a gRPC service for high-performance, language-neutral access to the graph database.

Default port: 50051 (configurable via --grpc-listen).

Service Overview

The TraverseService (package traverse.v1) provides RPCs for query execution, node/edge CRUD, transactions, and schema inspection.

Query Execution

ExecuteQuery (server-streaming)

Sends a Cypher query and receives a stream of responses: header (column names), rows, and footer (stats + timing).

rpc ExecuteQuery(ExecuteQueryRequest) returns (stream ExecuteQueryResponse);

message ExecuteQueryRequest {
  string query = 1;
  map<string, Value> parameters = 2;
  string transaction_id = 3;   // for explicit transactions
  string database = 4;         // empty = default database
  repeated string bookmarks = 5;
  string access_mode = 6;      // "r" or "w"
  uint64 timeout_ms = 7;       // 0 = no timeout
}

QueryChannel (bidirectional streaming)

Multiplexed bidirectional stream with request_id routing for concurrent queries over a single connection.

rpc QueryChannel(stream QueryChannelRequest) returns (stream QueryChannelResponse);

Node Operations

Edge Operations

Property Updates

rpc UpdateProperties(UpdatePropertiesRequest) returns (UpdatePropertiesResponse);

Update properties on a node or edge by element ID.

Transactions

Schema & Index Management

Value Types

The protobuf Value message supports:

• Scalars: null, bool, int64, double, string, bytes
• Collections: ListValue, MapValue
• Graph elements: NodeValue, EdgeValue, PathValue
• Temporal: temporal_value (ISO-8601 encoded string)

Request Metadata

All query requests support these optional fields:

• database — target database (empty = server default)
• bookmarks — causal consistency bookmarks
• access_mode — "r" (read) or "w" (write)
• timeout_ms — query timeout in milliseconds (0 = no timeout)
• notifications — severity and category filtering

Complete RPC Summary

21 RPCs total:

Client Examples

Python (grpcio)

import grpc
import traverse_pb2, traverse_pb2_grpc

channel = grpc.insecure_channel("localhost:50051")
stub = traverse_pb2_grpc.TraverseServiceStub(channel)

request = traverse_pb2.ExecuteQueryRequest(
    query="MATCH (n) RETURN n LIMIT 5",
    database="mydb"
)
for response in stub.ExecuteQuery(request):
    print(response)

Go

conn, _ := grpc.Dial("localhost:50051", grpc.WithInsecure())
client := pb.NewTraverseServiceClient(conn)

stream, _ := client.ExecuteQuery(ctx, &pb.ExecuteQueryRequest{
    Query:    "MATCH (n) RETURN n LIMIT 5",
    Database: "mydb",
})
for {
    resp, err := stream.Recv()
    if err == io.EOF { break }
    fmt.Println(resp)
}

.NET (Traverse.Client)

using Grpc.Net.Client;
using Traverse.Client;

var channel = GrpcChannel.ForAddress("http://localhost:50051");
var client = new TraverseService.TraverseServiceClient(channel);

var stream = client.ExecuteQuery(new ExecuteQueryRequest
{
    Query = "MATCH (n) RETURN n LIMIT 5",
    Database = "mydb"
});

await foreach (var response in stream.ResponseStream.ReadAllAsync())
    Console.WriteLine(response);