graph_query
Graph traversals and Cypher queries for Active Record on PostgreSQL. Declare edges on your models from the associations they already have; walk them in a Ruby chain, a Cypher-style pattern or a Cypher query; get Active Record relations back. Every walk is one recursive CTE, so it needs nothing installed in the database: no Apache AGE, no extension. It runs on Heroku Postgres, RDS, Supabase or your laptop.
Docs: https://lwm-luminx.github.io/graph_query/
gem 'graph_query'class Locale < ApplicationRecord
has_many :children, class_name: 'Locale', foreign_key: :parent_id
has_many :venues
graph_edge :contains, association: :children
graph_edge :contains, to: Locale, through: LocaleGrouping, source: :super_locale_id, target: :member_locale_id
graph_edge :has_venue, association: :venues
end
class Venue < ApplicationRecord
graph_edge :hosts, association: :events
end
washington = Locale.where(name: 'Washington')
washington.traverse(:contains, depth: 0..) # the state and everything in it
washington.traverse(:contains, depth: 0..).traverse(:has_venue) # every venue in the state
.where(kind: 'bar').order(:name) # ... still a relation
seattle.traverse(:contains, direction: :in, depth: 1..) # everything Seattle lies within
GraphQuery.match('(s:Locale)-[:contains*0..]->()-[:has_venue]->(v:Venue)-[:hosts]->(e:Event)',
s: washington, e: Event.upcoming).nodes(:v) # venues with upcoming events
GraphQuery.cypher(<<~CYPHER, state: 'Washington') # the same, as Cypher
MATCH (s:Locale {name: $state})-[:contains*0..]->()-[:has_venue]->(v:Venue)-[:hosts]->(e:Event)
WHERE e.starts_at > '2026-12-01' AND v.kind = 'bar'
RETURN v ORDER BY v.name LIMIT 20
CYPHERWhat's in it
-
Edges from
belongs_to,has_many/has_oneandhas_many :throughassociations, from a join model named outright, or from SQL. Several declarations with one name union into one kind of edge. -
Walks with any depth (
1,2..4,0..,1..), in any direction, filtered on where they arrive (to:,where:), on every node they pass (through:), and on the edges' own rows (edge_where:). Cycles end unbounded walks. -
Results as relations, plus hop counts (
with_depth), mixed-modelpairs/records, polymorphic roll-ups (polymorphic(Comment.all, :commentable)), per-start grouping for GraphQL dataloaders (by_origin), andpaths. -
Patterns (
GraphQuery.match) and Cypher (GraphQuery.cypher):MATCHwith property maps and several paths,WHERE,RETURN,ORDER BY,SKIP,LIMIT,$params. -
Writes:
GraphQuery.transactionlinks and unlinks through the same edges, andgraph_mutationmarks model methods that write the graph in one transaction. -
GraphQL (
require 'graph_query/graphql'): batched fields backed by walks, a field per declared edge, and mutation fields from graph mutations. -
Types: RBS signatures in
sig/and a Sorbet RBI inrbi/. -
Speed: edges join through
CROSS JOIN LATERAL, so each hop reads the edge table through its index.
Requires Ruby 4.0+, Active Record 7.1+ and PostgreSQL.
Docs
The guide is in docs/ and published at https://lwm-luminx.github.io/graph_query/: getting started, declaring edges, walking, results, patterns, Cypher queries, writing edges, GraphQL, how it runs and the reference.
Development
bundle install
createdb graph_query_test
GRAPH_QUERY_DATABASE_URL=postgres:///graph_query_test bundle exec rake # specs, RuboCop, rbs validate
bundle exec rake docs # builds the docs site into site/ (needs pandoc)The specs are shared examples (spec/support/graph_query_examples.rb) over a small graph in gq_ tables, so an app
can run the same examples against its own database.
Releasing
Bump GraphQuery::VERSION and CHANGELOG.md, merge to main, then run the Release workflow on main (Actions →
Release → Run workflow) or push a tag vX.Y.Z. It runs the specs, tags the version (or checks the tag matches it), publishes the gem to RubyGems with trusted publishing (no API key is
stored), and creates a GitHub release.
License
MIT, copyright Love Wins Media, Inc. See LICENSE.txt. graph_query was built for AudienceKit.