0.0
The project is in a healthy, maintained state
Declare edges on Active Record models from their associations, join tables or SQL, then walk them with recursive CTEs: fixed and variable-length hops, both directions, node and edge filters, Cypher queries (MATCH, WHERE, RETURN), and results that come back as Active Record relations.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

>= 1.5
 Project Readme

graph_query

CI Gem

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
CYPHER

What's in it

  • Edges from belongs_to, has_many/has_one and has_many :through associations, 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-model pairs/records, polymorphic roll-ups (polymorphic(Comment.all, :commentable)), per-start grouping for GraphQL dataloaders (by_origin), and paths.
  • Patterns (GraphQuery.match) and Cypher (GraphQuery.cypher): MATCH with property maps and several paths, WHERE, RETURN, ORDER BY, SKIP, LIMIT, $params.
  • Writes: GraphQuery.transaction links and unlinks through the same edges, and graph_mutation marks 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 in rbi/.
  • 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.