Documentation
pg_warren provides deep traversal and whole-graph computation inside PostgreSQL, over nodes and edges in ordinary tables. Think pgvector, but for graphs: a graph index and compute engine beside your data, queried through SQL functions.
Start with a working example
Section titled “Start with a working example”- Install the extension for your PostgreSQL major and platform. PostgreSQL 15–18 are supported on Linux. Managed providers must adopt the extension before you can install it there; until then, run it on a server of your own beside a managed database.
- Create your first graph from two small tables, run a breadth-first search, and compute PageRank. Then explore the example library for complete walkthroughs over a reproducible graph of 10,000 people: communities, semirings, taint propagation, paths, and graph versions.
- Read graphs and versions before connecting a changing application dataset. Queries read a built graph version; a later table change appears after a refresh.
Choose the right query
Section titled “Choose the right query”For the architectural comparison with pgGraph, Apache AGE, OneSparse and pgRouting, read where pg_warren fits. The principal distinction from pgGraph is whole-graph computation over explicit, transactional graph versions.
For a shallow query with a small frontier, indexed joins or a recursive CTE are usually the right starting point. pg_warren is useful when a traversal touches many rows, or when a computation repeatedly processes the graph. Frontier size matters more than hop count: three hops can mean a thousand intermediate rows or a billion, depending on degree.
| Task | Read |
|---|---|
| Find neighbours, reachable nodes, paths, or typed walks | Traversal |
| Rank nodes, work with vectors, or write iterative algorithms | Compute |
| Find communities or build community-level graphs | Communities |
| Compare a staged build before committing a data change | Change detection |
| Check a function’s exact arguments and return type | SQL reference |
| Configure memory, the shared cache, or compute threads | Settings and limits |
| Use pg_warren with Amazon RDS or another managed database | Beside a managed database |
Traversals that return nodes use external ids that you can join back to your tables. Scalar lookups return values such as a degree or a reachability result. Computations work with named vectors bound to a graph version; their results can also be read as SQL rows. The functions compose with the rest of a query.
Understand the operating model
Section titled “Understand the operating model”A graph is defined by a node query and an edge query. A refresh builds a new immutable version, persisted transactionally in extension tables. Versions can be staged, compared, promoted, retained, or dropped. The tables remain the source of truth.
Read the architecture overview for the storage and computation model, and operations for pooling, backups, upgrades, replicas, and troubleshooting.
Evaluate performance
Section titled “Evaluate performance”The performance comparison sets pg_warren’s features beside pgGraph, igraph and Neo4j, and summarises measured results against igraph and Neo4j, with and without GDS. The benchmark methodology and full results describe the datasets, engine settings, correctness checks, and comparison limits. Performance depends on the workload; the results include both wins and losses.
For development prerequisites, checks, and release procedures, see contributing.