astraeadb

Python client for AstraeaDB, a graph database with vector search written in Rust. Talks to the AstraeaDB server over newline-delimited JSON-over-TCP (no dependencies) with an optional Apache Arrow Flight transport and pandas integration.

Installation

pip install astraeadb                 # core client, zero dependencies
pip install "astraeadb[arrow]"        # + Arrow Flight transport (pyarrow)
pip install "astraeadb[pandas]"       # + DataFrame helpers (pandas)
pip install "astraeadb[all]"          # everything

Requires Python 3.9+. A running AstraeaDB server is required — see the AstraeaDB documentation.

Quick start

from astraeadb import AstraeaClient

with AstraeaClient(host="127.0.0.1", port=7687) as client:
    alice = client.create_node(["Person"], {"name": "Alice", "age": 30})
    bob = client.create_node(["Person"], {"name": "Bob"})
    client.create_edge(alice, bob, "KNOWS", weight=0.9)

    # Traversals
    client.bfs(alice, max_depth=2)
    client.dfs(alice, max_depth=2)
    client.shortest_path(alice, bob, weighted=True)

    # Lookups
    client.find_by_label("Person")
    client.find_edge_by_type("KNOWS")

    # Vector similarity (results carry node_id + distance; smaller is closer)
    hits = client.vector_search([0.1, 0.9, 0.3], k=5)

    # Graph algorithms (computed server-side)
    client.run_pagerank()
    client.run_louvain()
    client.run_betweenness_centrality()

    # GQL
    client.query("MATCH (p:Person) RETURN p.name")

Features

• CRUD — create/read/update/delete nodes and edges with arbitrary properties
• Lookups — find_by_label, find_edge_by_type, bulk delete_by_label
• Traversals — bfs, dfs, shortest_path, neighbors
• Temporal queries — time-travel variants (bfs_at, dfs_at, neighbors_at, shortest_path_at) over edge validity windows
• Graph algorithms — run_pagerank, run_louvain, run_connected_components, run_degree_centrality, run_betweenness_centrality
• Vector search — vector_search (k-NN), hybrid_search (graph + vector), semantic_neighbors, semantic_walk
• GraphRAG — extract_subgraph and graph_rag for LLM context assembly
• Statistics — graph_stats and raw get_subgraph export
• GQL — query for Cypher-style graph queries
• Batch — create_nodes, create_edges, delete_nodes, delete_edges
• DataFrames — import/export helpers in astraeadb.dataframe (pandas)
• Arrow Flight — high-throughput columnar transport when pyarrow is installed

Clients

from astraeadb import JsonClient       # explicit JSON/TCP
from astraeadb import ArrowClient      # explicit Arrow Flight (needs pyarrow)
from astraeadb import AstraeaClient    # unified, auto-selecting

License

MIT © 2026 James Harris.