# pgGraph User Guide

`graph` is a PostgreSQL extension that lets you search, traverse, and explain
relationships in ordinary PostgreSQL tables. You register the tables and
relationships that matter, build the graph, and keep using SQL.

PostgreSQL remains the source of truth. pgGraph handles the graph index,
bounded traversal, path reconstruction, persistence, and maintenance behind the
`graph` schema.

<Callout type="info">
The current public API is PostgreSQL SQL functions in the `graph` schema,
including a documented GQL-compatible subset through `graph.gql()`. SQL/PGQ is
not supported by pgGraph 1.0 on PostgreSQL 14 through 18.
</Callout>

## What It Does For You

| Area | What you get |
|---|---|
| Table registration | Manual registration with `graph.add_table()` or discovery with `graph.auto_discover()` and `graph.auto_discover_tables()` |
| Edge registration | FK-style edges and edge-table style relationships through `graph.add_edge()` |
| Search | Source-table SQL search over registered columns with `contains`, `exact`, `prefix`, and `token` modes |
| Traversal | Bounded BFS and DFS over CSR edges with direction, edge type, table, tenant, filter, hydration, pagination, and circuit breaker options |
| GQL | A documented GQL-compatible graph-pattern subset, narrow mapped writes (`CREATE`, `SET`, `REMOVE`, `DELETE`, `DETACH DELETE`, `MERGE`), and JSONB row output |
| Paths | Unweighted shortest path, weighted shortest path when edge weights are registered, readable path helpers, and workflow wrappers |
| Components | Admin-only connected component summaries and paginated component membership |
| Filtering | Traversal-time typed filter pushdown for registered filter columns |
| Aggregation | Strict JSON traversal specs for path counting and server-side aggregates |
| Sync | Manual rebuild, trigger-log apply, foreground/background maintenance, and full rebuild vacuum |
| Persistence | Fast backend startup from a validated `.pggraph` artifact when enabled |

## First Build

```sql
CREATE EXTENSION graph;

SELECT graph.add_table(
  'public.customers'::regclass,
  id_column := 'id',
  columns := ARRAY['name', 'email']
);

SELECT graph.add_table(
  'public.orders'::regclass,
  id_column := 'id',
  columns := ARRAY['status']
);

SELECT graph.add_edge(
  from_table := 'public.orders'::regclass,
  from_column := 'customer_id',
  to_table := 'public.customers'::regclass,
  to_column := 'id',
  label := 'placed_by',
  bidirectional := true
);

SELECT * FROM graph.build();
```

## First Queries

```sql
SELECT *
FROM graph.search('name', 'Alice', mode := 'contains');

SELECT *
FROM graph.traverse(
  'public.customers'::regclass,
  '42',
  max_depth := 3
);

SELECT *
FROM graph.shortest_path(
  'public.customers'::regclass,
  '42',
  'public.customers'::regclass,
  '99'
);

SELECT row
FROM graph.gql(
  'MATCH (o:orders)-[:placed_by]->(c:customers)
   RETURN o.status AS status, c.name AS customer
   LIMIT 10'
);
```

## Mental Model

```text
PostgreSQL tables
      |
      | graph.add_table(), graph.add_edge(), graph.add_filter_column()
      v
registered graph definition
      |
      | graph.build()
      v
graph index
      |
      | graph.persist_on_build = true
      v
persisted graph files in PostgreSQL-managed storage
      |
      | graph.auto_load = true
      v
bounded SQL and GQL results
```

When persistence is enabled, pgGraph stores the index in PostgreSQL-managed
storage so later backends can load it without rebuilding. See
[Build And Persistence](/user_guide/build-and-persistence) for file layout,
validation, and compatibility details.

For day-to-day SQL use, that is the whole model: PostgreSQL source tables, a
registered graph definition, a rebuildable graph index, and ordinary SQL
results. Implementation details are documented in the
[Contributor Architecture](/contributor_guide/architecture).

```mermaid
flowchart TD
  A["Source tables"] --> B["Registered graph"]
  B --> C["graph.build()"]
  C --> D["Graph index"]
  D --> E["SQL and GQL queries"]
  D --> F["Persisted graph files"]
  F --> D
```

## Recommended Reading Order

1. [Quickstart](/quickstart) to try the full loop in a scratch database.
2. [Installation](/user_guide/installation) to compile, install, and load the extension.
3. [Schema Registration](/user_guide/schema-registration) to model tables and edges.
4. [Build And Persistence](/user_guide/build-and-persistence) to build and load the base graph.
5. [Querying](/user_guide/querying) for search, traversal, workflow wrappers, paths, and components.
6. [Sync And Maintenance](/user_guide/sync-and-maintenance) to choose refresh workflows.
7. [Limitations And Fit](/user_guide/limitations-and-fit) before production rollout.
8. [Playground](/user_guide/playground) to run the Docker-backed SQL inspector.
9. [SQL API Reference](/user_guide/api-reference) for complete function signatures and return columns.

<Callout type="warning">
The active engine is built from source tables and may include backend-local sync
overlays. Background build and maintenance workers can rebuild and persist a new
base graph, but they do not continuously mutate every backend's already-loaded
engine in place.
</Callout>