PostgreSQL 19devel adds SQL/PGQ, GRAPH_TABLE, and property graph DDL in core. Use this cheat sheet to query complex graphs faster. Read now.
What SQL/PGQ brings into core PostgreSQL
SQL/PGQ is the SQL property-graph query model now available in PostgreSQL 19devel as a first-class feature set. Instead of bolting graph logic onto ad hoc joins or recursive CTEs alone, you model entities as vertices, relationships as edges, and query them with graph-oriented constructs that stay inside the database. The headline pieces are property graph DDL, which defines the graph schema, and GRAPH_TABLE, which is the main surface for pattern matching and projecting results back into ordinary relational rows.
Treat this as a modeling choice, not a separate product. Graph definitions live next to tables and views. You still use SQL for filters, aggregates, and joins; PGQ adds the vocabulary for multi-hop relationships so path-shaped questions stop requiring long chains of self-joins that are hard to read and easy to get wrong.
Define the graph before you query it
Start with property graph DDL. Map source tables (or views) to vertex and edge labels, declare which columns are properties, and name the direction of each edge so patterns remain unambiguous. Keep labels stable and business-meaningful: a person, account, order, or dependency should read the same in the graph as in the rest of your schema. Prefer thin edge tables that carry only the foreign keys and edge attributes you actually need; bloated edge properties slow pattern matching and obscure intent.
Validate cardinality early. One-to-many and many-to-many relationships should appear as distinct edge types when their semantics differ. If two relationships share the same endpoints but mean different things (for example “owns” versus “manages”), give them separate labels. That discipline pays off when GRAPH_TABLE patterns grow beyond a single hop.
Query patterns with GRAPH_TABLE
GRAPH_TABLE is where you express path patterns: match a sequence of vertices and edges, bind variables along the path, apply predicates on properties, and return columns the rest of SQL can consume. Think in small, named patterns first—one hop, then two—before composing longer walks. Project only the identifiers and properties you need; wide result shapes make downstream joins harder to optimize mentally and physically.
- Anchor on a selective start vertex (known id, type, or tight property filter) so the match does not fan out across the whole graph.
- Constrain edge labels and directions explicitly; leave nothing to implicit “any relationship.”
- Push property filters as close to the matched element as the syntax allows so intermediate paths stay small.
- Return a relational shape (ids, scores, hop counts) and finish with ordinary
WHERE,GROUP BY, andORDER BYoutside the graph match when that is clearer.
Use recursive CTEs when the problem is open-ended traversal over a single parent–child table with simple rules. Prefer SQL/PGQ when multiple entity types and labeled relationships matter, when path structure is the query, or when the same graph will be reused across several reports and services.
Practical habits for faster graph work
Index the columns that back vertex keys and edge endpoints the same way you would for heavy join workloads; PGQ does not replace sound relational indexing. Keep graph DDL in version control next to migrations so environments stay aligned. Document which tables are authoritative sources for each label so dual-write or ETL mistakes do not silently desync the graph from the tables applications already trust.
When a query feels slow, shrink the pattern: fewer free variables, tighter labels, earlier filters, and smaller projections. Compare the graph form to an equivalent multi-join query only after both express the same business question—then keep the version that is easier to maintain without sacrificing correctness. Used this way, SQL/PGQ and GRAPH_TABLE turn complex relationship questions into readable, reusable SQL instead of one-off join mazes.