Client for the 'AstraeaDB' Graph Database

Provides a client for 'AstraeaDB', a graph database with vector search capabilities. Supports node and edge create, read, update, and delete operations, label and edge-type lookups, graph traversals (breadth-first search, depth-first search, shortest path), temporal (time-travel) queries, graph algorithms (PageRank, Louvain community detection, connected components, and degree and betweenness centrality), vector similarity search, hybrid graph-vector search, Graph Query Language (GQL) execution, and graph-based retrieval-augmented generation (subgraph extraction with large language model integration). Communicates with the 'AstraeaDB' server over a JSON-over-TCP protocol. An optional 'Apache Arrow Flight' transport is available for high-performance bulk operations when the 'arrow' package is installed.

AstraeaDB

An R client for AstraeaDB, a graph database with vector search written in Rust. AstraeaDB provides node and edge CRUD operations, label and edge-type lookups, graph traversals (BFS, DFS, shortest path), temporal queries, graph algorithms (PageRank, Louvain, connected components, centrality), vector similarity search, hybrid graph-vector search, GQL query execution, and GraphRAG (subgraph extraction with LLM integration).

Installation

Install the development version from GitHub:

# install.packages("remotes")
remotes::install_github("AstraeaDB/R-AstraeaDB")

Prerequisites

A running AstraeaDB server is required. See the AstraeaDB documentation for installation and startup instructions.

Quick start

library(AstraeaDB)

# Connect to a local AstraeaDB server
client <- astraea_connect()

# Create nodes
alice <- client$create_node("Person", list(name = "Alice", age = 30))
bob   <- client$create_node("Person", list(name = "Bob", age = 25))

# Create an edge
client$create_edge(alice, bob, "KNOWS", list(since = "2024-01-01"))

# Traverse the graph
client$neighbors(alice)
client$bfs(alice, max_depth = 3)
client$shortest_path(alice, bob)

# Run a GQL query
client$query("MATCH (p:Person) WHERE p.age > 20 RETURN p")

# Disconnect when done
client$disconnect()

Features

Core graph operations

• Node and edge CRUD -- create, read, update, and delete nodes and edges
• Graph traversals -- BFS, DFS, shortest path (weighted and unweighted), neighbor queries with direction and edge-type filtering
• Lookups -- find nodes by label, find edges by type, bulk-delete by label
• Batch operations -- bulk create and delete for nodes and edges
• Data frame integration -- import nodes/edges from data frames and export query results back to data frames

Vector and AI capabilities

• Vector similarity search -- k-nearest neighbor search over node embeddings
• Hybrid search -- blend graph proximity with vector similarity using a tunable alpha parameter
• Semantic search -- rank neighbors by concept similarity or perform greedy semantic walks
• GraphRAG -- extract subgraphs and feed them to an LLM for retrieval-augmented generation

Temporal queries

• Time-travel -- query the graph as it existed at any point in time using edge validity windows (valid_from / valid_to)

Graph algorithms

• PageRank, Louvain, connected components, degree and betweenness centrality -- classic analytics computed server-side over the whole graph or a node subset
• Graph statistics and subgraph export -- node/edge counts, label distribution, and raw subgraph retrieval for visualization

Transport options

Arrow Flight support is optional and activates automatically when the arrow package is installed.

Clients

# Standard JSON/TCP client
client <- astraea_connect(host = "127.0.0.1", port = 7687)

# Arrow Flight client (requires the arrow package)
arrow_client <- astraea_arrow_connect(uri = "grpc://localhost:7689")

# Unified client -- delegates CRUD to JSON/TCP, queries to Arrow when available
unified <- UnifiedClient$new(host = "127.0.0.1", port = 7687)
unified$connect()

Vignettes

The package ships with four vignettes:

• Introduction -- overview of AstraeaDB and its data model
• Getting started -- detailed walkthrough of CRUD, traversals, and queries
• Advanced features -- vector search, temporal queries, and GraphRAG
• PCAP analysis -- worked example converting network packet captures into a graph

Build vignettes locally with:

devtools::build_vignettes()

Dependencies

License

MIT