grafeo-llamaindex 0.1.0

LlamaIndex PropertyGraphStore backed by GrafeoDB embedded graph database

grafeo-llamaindex

LlamaIndex PropertyGraphStore backed by GrafeoDB — an embedded graph database with native vector search.

Build knowledge graphs from documents, query them with GQL, and run vector similarity search — all in a single .db file. No servers, no infrastructure.

Install

pip install grafeo-llamaindex

Quickstart

from llama_index.core import PropertyGraphIndex, SimpleDirectoryReader
from grafeo_llamaindex import GrafeoPropertyGraphStore

documents = SimpleDirectoryReader("./data").load_data()

graph_store = GrafeoPropertyGraphStore(db_path="./knowledge_graph.db")

index = PropertyGraphIndex.from_documents(
    documents,
    property_graph_store=graph_store,
    embed_kg_nodes=True,
)

retriever = index.as_retriever(include_text=True)
nodes = retriever.retrieve("What are the key relationships?")

Features

• Full PropertyGraphStore — all 8 abstract methods implemented (get, get_triplets, get_rel_map, upsert_nodes, upsert_relations, delete, structured_query, vector_query)
• Structured + vector queries — supports_structured_queries = True and supports_vector_queries = True in a single store
• Embedded database — no Docker, no cloud, no external services. Just pip install grafeo
• Single-file persistence — your entire knowledge graph lives in one .db file
• Native HNSW vector search — embeddings stored alongside graph nodes, no separate vector DB needed
• Multi-language queries — GQL, Cypher, Gremlin, GraphQL, and SPARQL all supported
• Built-in graph algorithms — PageRank, Louvain, shortest paths, centrality, and 30+ more via graph_store.client.algorithms

API Reference

GrafeoPropertyGraphStore

from grafeo_llamaindex import GrafeoPropertyGraphStore

store = GrafeoPropertyGraphStore(
    db_path=None,                # str | None — path for persistent storage, None for in-memory
    embedding_dimensions=1536,   # int — vector dimensions for HNSW index
    embedding_metric="cosine",   # str — "cosine", "euclidean", "dot_product", or "manhattan"
)

Properties:

• store.client — access the underlying grafeo.GrafeoDB instance for direct queries and algorithms
• store.supports_structured_queries — True
• store.supports_vector_queries — True

Methods (PropertyGraphStore interface):

Method	Description
upsert_nodes(nodes)	Insert or update EntityNode / ChunkNode objects
upsert_relations(relations)	Insert edges between existing nodes
get(properties, ids)	Retrieve nodes by ID or property filter
get_triplets(entity_names, relation_names, ids)	Get (source, relation, target) triplets
get_rel_map(graph_nodes, depth, ignore_rels)	BFS traversal from seed nodes
delete(entity_names, relation_names, ids)	Remove nodes and/or edges
structured_query(query)	Execute raw GQL/Cypher (or Gremlin with g. prefix)
vector_query(query)	HNSW similarity search over node embeddings
get_schema() / get_schema_str()	Inspect graph labels, edge types, and properties
persist(path)	Save in-memory database to disk
close()	Close the database connection

Comparison

	Neo4j	FalkorDB	Grafeo
Requires server	Yes	Yes	No (embedded)
Vector search	Plugin (5.x+)	Limited	Native HNSW
Graph algorithms	GDS plugin ($)	Built-in	Built-in (30+)
Query languages	Cypher	Cypher	GQL, Cypher, Gremlin, GraphQL, SPARQL
Deployment	Docker/Cloud	Docker/Cloud	pip install grafeo
Persistence	Server-managed	Server-managed	Single .db file

Examples

See the examples/ directory:

• basic_graph_rag.py — build a Property Graph Index from documents and query it
• hybrid_retrieval.py — structured queries + vector search + PageRank, all in one script

Development

uv sync                  # install deps
uv run pytest -v         # run tests
uv run ruff check .      # lint
uv run ruff format .     # format
uv run ty check          # type check

License

Apache-2.0