Appendix B: Client API Reference

A side-by-side reference of every operation across all four official AstraeaDB client libraries: Python, R, Go, and Java. Use this page to quickly translate code between languages or to look up the exact method signature you need.

B.1 Connection Management

Operation	Python	R	Go	Java
Create client	`AstraeaClient(host, port)`	`AstraeaClient$new(host, port)`	`astraeadb.NewClient(WithAddress(h, p))`	`UnifiedClient.builder().host(h).port(p).build()`
Connect	`client.connect()` or context manager	`client$connect()`	`client.Connect(ctx)`	`client.connect()`
Close	`client.close()`	`client$close()`	`client.Close()`	`client.close()` (auto with try-with-resources)
Ping	`client.ping()`	`client$ping()`	`client.Ping(ctx)`	`client.ping()`

Context managers and auto-close In Python, prefer with AstraeaClient(host, port) as client: to ensure the connection is closed automatically. In Java, use try-with-resources: try (var client = UnifiedClient.builder()...build()) { ... }. In Go, use defer client.Close() after connecting.

B.2 Node Operations

Operation	Python	R	Go	Java
Create	`create_node(labels, props, embedding)`	`create_node(labels, props, embedding)`	`CreateNode(ctx, labels, props, embedding)`	`createNode(labels, props, embedding)`
Get	`get_node(id)`	`get_node(id)`	`GetNode(ctx, id)`	`getNode(id)`
Update	`update_node(id, props)`	`update_node(id, props)`	`UpdateNode(ctx, id, props)`	`updateNode(id, props)`
Delete	`delete_node(id)`	`delete_node(id)`	`DeleteNode(ctx, id)`	`deleteNode(id)`

B.3 Edge Operations

Operation	Python	R	Go	Java
Create	`create_edge(src, tgt, type, props, weight, valid_from, valid_to)`	`create_edge(src, tgt, type, props, weight, valid_from, valid_to)`	`CreateEdge(ctx, src, tgt, edgeType, props, weight, validFrom, validTo)`	`createEdge(src, tgt, type, props, weight, validFrom, validTo)`
Get	`get_edge(id)`	`get_edge(id)`	`GetEdge(ctx, id)`	`getEdge(id)`
Update	`update_edge(id, props)`	`update_edge(id, props)`	`UpdateEdge(ctx, id, props)`	`updateEdge(id, props)`
Delete	`delete_edge(id)`	`delete_edge(id)`	`DeleteEdge(ctx, id)`	`deleteEdge(id)`

B.4 GQL Query

Operation	Python	R	Go	Java
Execute GQL	`query(gql)`	`query(gql)`	`Query(ctx, gql)`	`query(gql)`

All four clients accept a GQL string and return the results as the language-native data structure: a list of dictionaries in Python, a list in R, a slice of maps in Go, and a List<Map<String, Object>> in Java.

B.5 Traversals

Operation	Python	R	Go	Java
BFS	`bfs(start, max_depth)`	`bfs(start, max_depth)`	`Bfs(ctx, start, maxDepth)`	`bfs(start, maxDepth)`
Shortest Path	`shortest_path(from_id, to_id, weighted)`	`shortest_path(from_id, to_id, weighted)`	`ShortestPath(ctx, fromID, toID, weighted)`	`shortestPath(fromId, toId, weighted)`
Neighbors	`neighbors(id, direction, edge_type)`	`neighbors(id, direction, edge_type)`	`Neighbors(ctx, id, direction, edgeType)`	`neighbors(id, direction, edgeType)`

Direction values The direction parameter accepts "outgoing", "incoming", or "both" across all four clients.

B.6 Vector Operations

Operation	Python	R	Go	Java
Vector Search	`vector_search(vec, k)`	`vector_search(vec, k)`	`VectorSearch(ctx, vec, k)`	`vectorSearch(vec, k)`
Hybrid Search	`hybrid_search(anchor, vec, hops, k, alpha)`	`hybrid_search(anchor, vec, hops, k, alpha)`	`HybridSearch(ctx, anchor, vec, hops, k, alpha)`	`hybridSearch(anchor, vec, hops, k, alpha)`
Semantic Neighbors	`semantic_neighbors(id, concept, dir, k)`	`semantic_neighbors(id, concept, dir, k)`	`SemanticNeighbors(ctx, id, concept, dir, k)`	`semanticNeighbors(id, concept, dir, k)`
Semantic Walk	`semantic_walk(start, concept, hops)`	`semantic_walk(start, concept, hops)`	`SemanticWalk(ctx, start, concept, hops)`	`semanticWalk(start, concept, hops)`

The alpha parameter In hybrid_search, the alpha parameter (0.0 to 1.0) controls the balance between vector similarity and structural proximity. A value of 0.0 means pure graph traversal; 1.0 means pure vector search. The default of 0.5 gives equal weight to both signals.

B.7 Temporal Operations

Operation	Python	R	Go	Java
Neighbors At	`neighbors_at(id, dir, ts, edge_type)`	`neighbors_at(id, dir, ts, edge_type)`	`NeighborsAt(ctx, id, dir, ts, edgeType)`	`neighborsAt(id, dir, ts, edgeType)`
BFS At	`bfs_at(start, depth, ts)`	`bfs_at(start, depth, ts)`	`BfsAt(ctx, start, depth, ts)`	`bfsAt(start, depth, ts)`
Shortest Path At	`shortest_path_at(from_id, to_id, ts, weighted)`	`shortest_path_at(from_id, to_id, ts, weighted)`	`ShortestPathAt(ctx, fromID, toID, ts, weighted)`	`shortestPathAt(fromId, toId, ts, weighted)`

Timestamp format The ts parameter accepts an ISO 8601 timestamp string (e.g., "2024-01-15T00:00:00Z") across all clients. The server evaluates edge validity intervals and returns only edges whose [valid_from, valid_to) range includes the given timestamp.

B.8 GraphRAG Operations

Operation	Python	R	Go	Java
Extract Subgraph	`extract_subgraph(center, hops, max_nodes, format)`	`extract_subgraph(center, hops, max_nodes, format)`	`ExtractSubgraph(ctx, center, hops, maxNodes, format)`	`extractSubgraph(center, hops, maxNodes, format)`
Graph RAG	`graph_rag(question, anchor, embedding, hops, max_nodes, format)`	`graph_rag(question, anchor, embedding, hops, max_nodes, format)`	`GraphRAG(ctx, question, anchor, embedding, hops, maxNodes, format)`	`graphRag(question, anchor, embedding, hops, maxNodes, format)`

Format parameter The format parameter controls how the extracted subgraph is serialized for LLM consumption. Supported values are "text" (human-readable linearization), "json" (structured JSON), and "markdown" (formatted for chat contexts).

B.9 Batch Operations

Operation	Python	R	Go	Java
Create Nodes	`create_nodes([...])`	`create_nodes(list(...))`	`CreateNodes(ctx, [...])`	`createNodes(List.of(...))`
Create Edges	`create_edges([...])`	`create_edges(list(...))`	`CreateEdges(ctx, [...])`	`createEdges(List.of(...))`

Batch operations accept a list of node or edge specifications and create them in a single round-trip to the server. This is significantly faster than issuing individual create calls in a loop, especially over a network connection.

B.10 Transport Protocols

Each client library supports one or more transport protocols. The table below shows which transports are available in each language and the corresponding client class to use.

Language	JSON-TCP	gRPC	Arrow Flight
Python	`JsonClient`	—	`ArrowClient`
R	`AstraeaClient`	—	`ArrowClient`
Go	`JSONClient`	`GRPCClient`	Planned
Java	`JsonClient`	`GrpcClient`	`FlightClient`

Choosing a transport

JSON-TCP is the simplest protocol and is available in every language. Best for development and small workloads.
gRPC offers efficient binary serialization and HTTP/2 multiplexing. Ideal for production microservices in Go and Java.
Arrow Flight provides zero-copy data transfer using Apache Arrow columnar format. Best for analytical workloads and large result sets in Python, R, and Java.

B.11 Unified Client (Java)

The Java SDK provides a UnifiedClient that can switch between transports at runtime. This is useful when different operations benefit from different protocols.

// Create a unified client with all three transports
var client = UnifiedClient.builder()
    .host("localhost")
    .port(7687)
    .grpcPort(7688)
    .flightPort(7689)
    .defaultTransport(Transport.GRPC)
    .build();

// Use gRPC for CRUD
client.createNode(List.of("Person"), props, embedding);

// Switch to Arrow Flight for large queries
client.setTransport(Transport.FLIGHT);
var results = client.query("MATCH (n:Person) RETURN n");

← Appendix A: GQL Quick Reference Appendix C: Configuration Reference →