graph_query 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 0d97f7a17d91148bc269333df46669bbc0aed839425f31ee25df6436a123a1dd
4
+ data.tar.gz: 234c3868337d050d02da0a3082ea457ec7870629c6d1266bd631faa3890c9535
5
+ SHA512:
6
+ metadata.gz: 4599fd8eb4d9b8c94831cb6c24fd0abefa233f34dbdbca581cc72825b478f1aec2e1a064f990f0805537ec5ec5d82b8276971b91f29fbad0ffc97c6c43a3a648
7
+ data.tar.gz: c0edd428cb86ae068f3577fe0a513d46a784b1d8238ae8e957d38e38fc5bdf2c50b801f5ae18ce15f8a9ea08df08a960219682b5315f79d04186749acf34cee8
data/CHANGELOG.md ADDED
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0 (2026-11-19)
4
+
5
+ - Computed edges: `graph_edge name, to:, computed: -> { ... }` (or a block) returns a relation or SQL, built each
6
+ time a query runs and compiled into the same single statement.
7
+ - `GraphQuery.transaction` writes through declared edges: `link`, `unlink`, `relink`, `linked?`, plus `create`,
8
+ `update` and `destroy`, in one database transaction. Foreign keys are set or cleared, and join rows created or
9
+ destroyed, wherever the edge is kept.
10
+ - `graph_mutation` marks a model method as a graph mutation: it runs in a transaction, is handed the graph, and
11
+ carries the argument and result types GraphQL needs.
12
+ - `require 'graph_query/graphql'` for graphql-ruby: `graph_field` (by edge, pattern or block; batched through
13
+ `GraphQL::Dataloader`; connections paginate in SQL), `graph_edges` (a field per declared edge), `graph_mutations`
14
+ (a mutation field per graph mutation), `TransactionalMutation` and `edge_mutation`.
15
+ - `to:`, `through:` and `via:` take model classes as well as names.
16
+ - RBS and RBI signatures for the above.
17
+
18
+ ## 0.1.0 (2026-11-19)
19
+
20
+ First release.
21
+
22
+ - `graph_edge` on Active Record models: edges from `belongs_to`, `has_many`/`has_one` and `has_many :through`
23
+ associations, from a join model named outright, or from SQL. Same-named declarations union.
24
+ - `traverse` walks with `depth:` (Integer or Range, unbounded allowed), `direction:` (`:out`, `:in`, `:both`), `to:`,
25
+ `where:`, `through:` and `edge_where:`; one `WITH RECURSIVE` statement per walk, edges joined through
26
+ `CROSS JOIN LATERAL`.
27
+ - Results as relations, plus `with_depth`, `pairs`, `records`, `polymorphic`, `by_origin`, `origin_pairs`, `paths` and
28
+ `to_sql`.
29
+ - `GraphQuery.match` for linear Cypher-style patterns with bound variables and property maps.
30
+ - `GraphQuery.cypher` for read-only Cypher: `MATCH` (several paths joined on shared variables), `WHERE`, `RETURN`,
31
+ `ORDER BY`, `SKIP`, `LIMIT` and `$params`.
32
+ - RBS signatures (`sig/`) and a Sorbet RBI (`rbi/`).
33
+ - `GraphQuery::Age`, a pass-through to Apache AGE where a database has it.
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Love Wins Media, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,96 @@
1
+ # graph_query
2
+
3
+ [![CI](https://github.com/lwm-luminx/graph_query/actions/workflows/ci.yml/badge.svg)](https://github.com/lwm-luminx/graph_query/actions/workflows/ci.yml)
4
+ [![Gem](https://img.shields.io/gem/v/graph_query.svg)](https://rubygems.org/gems/graph_query)
5
+
6
+ Graph traversals and Cypher queries for Active Record on PostgreSQL. Declare edges on your models from the
7
+ associations they already have; walk them in a Ruby chain, a Cypher-style pattern or a Cypher query; get Active Record
8
+ relations back. Every walk is one recursive CTE, so it needs nothing installed in the database: no Apache AGE, no
9
+ extension. It runs on Heroku Postgres, RDS, Supabase or your laptop.
10
+
11
+ **Docs: https://lwm-luminx.github.io/graph_query/**
12
+
13
+ ```ruby
14
+ gem 'graph_query'
15
+ ```
16
+
17
+ ```ruby
18
+ class Locale < ApplicationRecord
19
+ has_many :children, class_name: 'Locale', foreign_key: :parent_id
20
+ has_many :venues
21
+
22
+ graph_edge :contains, association: :children
23
+ graph_edge :contains, to: Locale, through: LocaleGrouping, source: :super_locale_id, target: :member_locale_id
24
+ graph_edge :has_venue, association: :venues
25
+ end
26
+
27
+ class Venue < ApplicationRecord
28
+ graph_edge :hosts, association: :events
29
+ end
30
+
31
+ washington = Locale.where(name: 'Washington')
32
+ washington.traverse(:contains, depth: 0..) # the state and everything in it
33
+ washington.traverse(:contains, depth: 0..).traverse(:has_venue) # every venue in the state
34
+ .where(kind: 'bar').order(:name) # ... still a relation
35
+ seattle.traverse(:contains, direction: :in, depth: 1..) # everything Seattle lies within
36
+
37
+ GraphQuery.match('(s:Locale)-[:contains*0..]->()-[:has_venue]->(v:Venue)-[:hosts]->(e:Event)',
38
+ s: washington, e: Event.upcoming).nodes(:v) # venues with upcoming events
39
+
40
+ GraphQuery.cypher(<<~CYPHER, state: 'Washington') # the same, as Cypher
41
+ MATCH (s:Locale {name: $state})-[:contains*0..]->()-[:has_venue]->(v:Venue)-[:hosts]->(e:Event)
42
+ WHERE e.starts_at > '2026-12-01' AND v.kind = 'bar'
43
+ RETURN v ORDER BY v.name LIMIT 20
44
+ CYPHER
45
+ ```
46
+
47
+ ## What's in it
48
+
49
+ - **Edges** from `belongs_to`, `has_many`/`has_one` and `has_many :through` associations, from a join model named
50
+ outright, or from SQL. Several declarations with one name union into one kind of edge.
51
+ - **Walks** with any depth (`1`, `2..4`, `0..`, `1..`), in any direction, filtered on where they arrive (`to:`,
52
+ `where:`), on every node they pass (`through:`), and on the edges' own rows (`edge_where:`). Cycles end unbounded
53
+ walks.
54
+ - **Results** as relations, plus hop counts (`with_depth`), mixed-model `pairs`/`records`, polymorphic roll-ups
55
+ (`polymorphic(Comment.all, :commentable)`), per-start grouping for GraphQL dataloaders (`by_origin`), and `paths`.
56
+ - **Patterns** (`GraphQuery.match`) and **Cypher** (`GraphQuery.cypher`): `MATCH` with property maps and several
57
+ paths, `WHERE`, `RETURN`, `ORDER BY`, `SKIP`, `LIMIT`, `$params`.
58
+ - **Writes**: `GraphQuery.transaction` links and unlinks through the same edges, and `graph_mutation` marks model
59
+ methods that write the graph in one transaction.
60
+ - **GraphQL** (`require 'graph_query/graphql'`): batched fields backed by walks, a field per declared edge, and
61
+ mutation fields from graph mutations.
62
+ - **Types**: RBS signatures in `sig/` and a Sorbet RBI in `rbi/`.
63
+ - **Speed**: edges join through `CROSS JOIN LATERAL`, so each hop reads the edge table through its index.
64
+
65
+ Requires Ruby 4.0+, Active Record 7.1+ and PostgreSQL.
66
+
67
+ ## Docs
68
+
69
+ The guide is in [docs/](docs/) and published at https://lwm-luminx.github.io/graph_query/:
70
+ [getting started](docs/01-getting-started.md), [declaring edges](docs/02-declaring-edges.md),
71
+ [walking](docs/03-walking.md), [results](docs/04-results.md), [patterns](docs/05-patterns.md),
72
+ [Cypher queries](docs/06-cypher.md), [writing edges](docs/07-writes.md), [GraphQL](docs/08-graphql.md),
73
+ [how it runs](docs/09-internals.md) and the [reference](docs/10-reference.md).
74
+
75
+ ## Development
76
+
77
+ ```sh
78
+ bundle install
79
+ createdb graph_query_test
80
+ GRAPH_QUERY_DATABASE_URL=postgres:///graph_query_test bundle exec rake # specs, RuboCop, rbs validate
81
+ bundle exec rake docs # builds the docs site into site/ (needs pandoc)
82
+ ```
83
+
84
+ The specs are shared examples (`spec/support/graph_query_examples.rb`) over a small graph in `gq_` tables, so an app
85
+ can run the same examples against its own database.
86
+
87
+ ## Releasing
88
+
89
+ Bump `GraphQuery::VERSION` and `CHANGELOG.md`, merge to main, then run the Release workflow on main (Actions →
90
+ 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
91
+ stored), and creates a GitHub release.
92
+
93
+ ## License
94
+
95
+ MIT, copyright Love Wins Media, Inc. See [LICENSE.txt](LICENSE.txt). graph_query was built for
96
+ [AudienceKit](https://audiencekit.com).
@@ -0,0 +1,82 @@
1
+ # Getting started
2
+
3
+ graph_query lets Active Record models on PostgreSQL be walked like a graph. You declare **edges** on your models from
4
+ the associations they already have, then **traverse** them in a Ruby chain or match them with a **Cypher-style
5
+ pattern**. Every walk compiles to one `WITH RECURSIVE` statement, and what comes back is an ordinary Active Record
6
+ relation you can keep chaining.
7
+
8
+ It needs nothing installed in the database: no Apache AGE, no extension. That is why it runs on Heroku Postgres.
9
+
10
+ ## Install
11
+
12
+ ```ruby
13
+ # Gemfile
14
+ gem 'graph_query'
15
+ ```
16
+
17
+ It needs Ruby 4.0+, Active Record 7.1+ and the `pg` adapter. Once loaded, every Active Record model gets
18
+ `graph_edge`, `traverse`, `graph` and `graph_match`. There is no generator, migration or initializer.
19
+
20
+ ## A first walk
21
+
22
+ The examples in this guide use a small schema of places, venues, events and people.
23
+
24
+ Say locales nest (a state contains cities, a city contains neighborhoods) and venues belong to a locale:
25
+
26
+ ```ruby
27
+ class Locale < ApplicationRecord
28
+ belongs_to :parent, class_name: 'Locale', optional: true
29
+ has_many :children, class_name: 'Locale', foreign_key: :parent_id
30
+ has_many :venues
31
+
32
+ graph_edge :contains, association: :children
33
+ graph_edge :within, association: :parent
34
+ graph_edge :has_venue, association: :venues
35
+ end
36
+ ```
37
+
38
+ Now walk them:
39
+
40
+ ```ruby
41
+ washington = Locale.where(name: 'Washington')
42
+
43
+ washington.traverse(:contains, depth: 0..) # the state and every locale inside it
44
+ washington.traverse(:contains, depth: 0..).traverse(:has_venue) # every venue in the state
45
+ .where(kind: 'bar').order(:name).limit(20) # ... still a relation
46
+
47
+ seattle = Locale.find_by(name: 'Seattle')
48
+ seattle.traverse(:within, depth: 1..) # every locale Seattle lies within
49
+ ```
50
+
51
+ The same walk as a pattern, and as a Cypher query:
52
+
53
+ ```ruby
54
+ GraphQuery.match('(s:Locale)-[:contains*0..]->()-[:has_venue]->(v:Venue)', s: washington)
55
+ .where(kind: 'bar')
56
+
57
+ GraphQuery.cypher(<<~CYPHER, state: 'Washington')
58
+ MATCH (s:Locale {name: $state})-[:contains*0..]->()-[:has_venue]->(v:Venue)
59
+ WHERE v.kind = 'bar'
60
+ RETURN v ORDER BY v.name
61
+ CYPHER
62
+ ```
63
+
64
+ ## The model in one paragraph
65
+
66
+ A **node** is a row of a model, named by `(node_type, node_id)`, where the type is the model's `polymorphic_name`.
67
+ An **edge** is a named kind of link from nodes of one model to nodes of another, read from a table: each row whose
68
+ source and target columns are both set is one edge. A **walk** starts from a set of nodes (a relation, a record, or
69
+ pairs) and takes **steps**; each step follows some edges one or more hops. The nodes the last step reaches are the
70
+ result.
71
+
72
+ ## Where to go next
73
+
74
+ - [Declaring edges](#declaring-edges): every way to turn a table into edges.
75
+ - [Walking](#walking): the options a step takes.
76
+ - [Results](#results): relations, depths, pairs, paths, roll-ups and dataloaders.
77
+ - [Patterns](#patterns): the same walks as text, with Ruby bindings.
78
+ - [Cypher queries](#cypher): MATCH, WHERE, RETURN, ORDER BY, SKIP, LIMIT.
79
+ - [Writing edges](#writes): transactions that link and unlink, and graph mutations on models.
80
+ - [GraphQL](#graphql): fields backed by walks, batched, and mutations from graph mutations.
81
+ - [How it runs](#internals): the SQL, performance and limits.
82
+ - [Reference](#reference): every method, errors, and RBS / Sorbet types.
@@ -0,0 +1,134 @@
1
+ # Declaring edges
2
+
3
+ Call `graph_edge name, ...` on the model the edge **leaves**. The name is a Symbol you pick (`:contains`,
4
+ `:has_venue`, `:rolls_up`). Several declarations with one name make one kind of edge that unions them, even across
5
+ models and target types.
6
+
7
+ ## From an association
8
+
9
+ The usual way. Name an association the model already has, and graph_query reads the edge from the table that holds
10
+ the foreign key.
11
+
12
+ | Association | Rows that are edges | Example |
13
+ | --- | --- | --- |
14
+ | `has_many` / `has_one` | the target's rows, pointing back with the foreign key | `graph_edge :contains, association: :children` |
15
+ | `belongs_to` | the owner's rows with the foreign key set | `graph_edge :within, association: :parent` |
16
+ | `has_many :through` a join model that `belongs_to` the target | the join model's rows | `graph_edge :billed_on, association: :events` |
17
+
18
+ What carries over from the association:
19
+
20
+ - **Its scope.** `has_many :published_posts, -> { where(published: true) }` makes edges only to published posts. The
21
+ scope must not take the owner record (a scope with an argument can't be walked, since there is no one owner).
22
+ - **`as:`** on a polymorphic `has_many` adds a condition on the type column, so only rows pointing at this model count.
23
+ - **The join model's scope** on a `:through` association.
24
+
25
+ What can't be an edge (each raises `ArgumentError` when the edge is first built):
26
+
27
+ - A polymorphic `belongs_to`: it has no one target model. Declare one edge per target with `through:` or `sql:`.
28
+ - A `:through` association with its own scope: that scope filters the target, not the join rows. Use `through:`
29
+ with `where:` instead.
30
+ - A `:through` chain through another `:through`, or one whose source isn't a `belongs_to`.
31
+
32
+ ## From a join model, named outright
33
+
34
+ When there's no association, or you need a different shape, name the table's model and its two columns:
35
+
36
+ ```ruby
37
+ class Locale < ApplicationRecord
38
+ graph_edge :contains, to: Locale, through: LocaleGrouping,
39
+ source: :super_locale_id, target: :member_locale_id
40
+ end
41
+ ```
42
+
43
+ - `to:` the model the edge arrives at.
44
+ - `through:` the model whose table holds the rows. It can be the target itself:
45
+ `graph_edge :rolls_up, to: EventSeries, through: EventSeries, source: :locale_id, target: :id`.
46
+ - `source:` the column holding the id of the node the edge leaves (defaults to the model's `foreign_key`).
47
+ - `target:` the column holding the id of the node it arrives at.
48
+
49
+ `to:` and `through:` take a class, which keeps them checked by Ruby and by type checkers, or a model name as a
50
+ String. A class loads that model when this one loads; a name is looked up only when a query first needs the edge, so
51
+ use one to break a load-order cycle or to name a model that may not exist in every app.
52
+
53
+ ## From SQL
54
+
55
+ For anything else, give SQL selecting `source_id` and `target_id`:
56
+
57
+ ```ruby
58
+ class Venue < ApplicationRecord
59
+ graph_edge :near, to: Venue, sql: <<~SQL
60
+ SELECT a.id AS source_id, b.id AS target_id
61
+ FROM venues a JOIN venues b ON a.id <> b.id AND ST_DWithin(a.location, b.location, 500)
62
+ SQL
63
+ end
64
+ ```
65
+
66
+ SQL edges can't take `edge_where:` filters (there's no model to check columns against), and the planner can only use
67
+ indexes if it can push the `source_id = ...` condition into your SQL.
68
+
69
+ ## Computed edges
70
+
71
+ When the SQL depends on something known only when the query runs (the current time, a setting, a scope built in
72
+ Ruby), give a callable instead. It runs each time a query is built, and returns a relation or a String that selects
73
+ `source_id` and `target_id`:
74
+
75
+ ```ruby
76
+ class Venue < ApplicationRecord
77
+ # Pass it as computed:
78
+ graph_edge :open_with, to: Venue, computed: lambda {
79
+ VenuePair.where('opens_at <= ? AND closes_at > ?', Time.current, Time.current)
80
+ .select('venue_a_id AS source_id, venue_b_id AS target_id')
81
+ }
82
+
83
+ # or as a block
84
+ graph_edge(:same_locale, to: Venue) do
85
+ Venue.joins('JOIN venues other ON other.locale_id = venues.locale_id AND other.id <> venues.id')
86
+ .select('venues.id AS source_id, other.id AS target_id')
87
+ end
88
+ end
89
+ ```
90
+
91
+ The result is compiled into the walk's one statement like any other edge. The callable only builds the SQL: it isn't
92
+ called once per node, so it can't run Ruby on each row. Computed edges, like SQL edges, take no `edge_where:` and
93
+ can't be written by a [transaction](#writes).
94
+
95
+ ## Filtering an edge's rows: `where:`
96
+
97
+ Every form takes `where:`, a Hash or a scope Proc run on the edge's table:
98
+
99
+ ```ruby
100
+ graph_edge :headlines, association: :event_people, where: { role: 'headliner' }
101
+ graph_edge :current_members, to: Person, through: Membership, source: :group_id, target: :person_id,
102
+ where: -> { where(ended_at: nil) }
103
+ ```
104
+
105
+ ## Unions
106
+
107
+ Declarations with the same name are one edge kind. A walk over `:contains` follows both of these:
108
+
109
+ ```ruby
110
+ graph_edge :contains, association: :children # a locale's sub-locales
111
+ graph_edge :contains, to: Locale, through: LocaleGrouping, # and, for a super locale, its members
112
+ source: :super_locale_id, target: :member_locale_id
113
+ ```
114
+
115
+ Edges with one name can also arrive at different models: a `:rolls_up` edge can go from a venue to its events **and**
116
+ its event series.
117
+
118
+ ## When edges are built
119
+
120
+ Declarations are lazy. They're stored as builders and turned into edges the first time a query needs them, so a
121
+ declaration may name a model that isn't loaded yet, and model classes can be declared in any order. When Rails reloads
122
+ a model, its declarations replace the old ones instead of adding to them.
123
+
124
+ To see what's declared:
125
+
126
+ ```ruby
127
+ GraphQuery.registry.all
128
+ # => [#<GraphQuery::Edge Locale -[:contains]-> Locale>, #<GraphQuery::Edge Locale -[:within]-> Locale>, ...]
129
+ ```
130
+
131
+ ## Ids
132
+
133
+ Node ids in one walk must share a SQL type, because each step's rows are unioned into one `node_id` column. Use uuid
134
+ everywhere, or bigint everywhere.
@@ -0,0 +1,121 @@
1
+ # Walking
2
+
3
+ Start a walk from a scope, a record, or a whole model, and add steps with `traverse`:
4
+
5
+ ```ruby
6
+ Locale.where(name: 'Washington').traverse(:contains, depth: 0..) # from a scope
7
+ locale.traverse(:within, depth: 1..) # from one record
8
+ Venue.traverse(:hosts) # from every row of a model
9
+ ```
10
+
11
+ Each `traverse` returns a new `GraphQuery::Query` (queries are immutable), so steps chain:
12
+
13
+ ```ruby
14
+ Locale.where(name: 'Washington')
15
+ .traverse(:contains, depth: 0..) # step 1: the state and everything in it
16
+ .traverse(:has_venue) # step 2: their venues
17
+ .traverse(:hosts, to: Event) # step 3: the events those venues host
18
+ ```
19
+
20
+ ## `traverse(names = nil, **options)`
21
+
22
+ `names` is a Symbol, an Array of Symbols (follow any of them), or `nil` / `:*` for every edge leaving the current
23
+ nodes.
24
+
25
+ | Option | Default | Meaning |
26
+ | --- | --- | --- |
27
+ | `depth:` | `1` | Hops, as an Integer or a Range. See below. |
28
+ | `direction:` | `:out` | `:out` (source to target), `:in` (target to source: ancestors, "who points at this"), or `:both`. |
29
+ | `to:` | any | Only arrive at these models: a model, a name, or an Array. |
30
+ | `where:` | none | Only arrive at nodes in this relation. An Array gives one relation per model (any may match). A Hash filters the one model the step reaches. |
31
+ | `through:` | none | Every node the step passes through, the last included, must be in this relation (or Array, one per model). Nodes of other models pass freely. |
32
+ | `edge_where:` | none | A Hash (or scope Proc) each edge's row must match. |
33
+
34
+ ### depth
35
+
36
+ | Value | Reaches |
37
+ | --- | --- |
38
+ | `1` | nodes one hop away (the default) |
39
+ | `3` | nodes exactly three hops away |
40
+ | `1..3` | one to three hops away |
41
+ | `0..` | the start nodes and everything reachable |
42
+ | `1..` | everything reachable, not the start nodes |
43
+ | `2..` | everything at least two hops away |
44
+ | `0..1` | the start nodes and their neighbours |
45
+
46
+ A node counts if **some** route reaches it within the range. Walks that can go on forever (`1..`, `0..`) stop when no
47
+ new node turns up, so cycles end them. Unbounded walks that have to count hops (`2..`, `with_depth`, `paths`) stop at
48
+ `GraphQuery.max_depth`, 32 by default:
49
+
50
+ ```ruby
51
+ GraphQuery.max_depth = 64
52
+ ```
53
+
54
+ ### direction
55
+
56
+ `:in` walks an edge backwards. With only `:contains` declared, you still get ancestors:
57
+
58
+ ```ruby
59
+ seattle.traverse(:contains, direction: :in, depth: 1..) # everything that contains Seattle
60
+ ```
61
+
62
+ `out`, `inbound` and `both` are shorthands:
63
+
64
+ ```ruby
65
+ query.out(:contains) # traverse(:contains, direction: :out)
66
+ query.inbound(:contains) # traverse(:contains, direction: :in)
67
+ query.both(:knows, depth: 1..2)
68
+ ```
69
+
70
+ ### to:, where:, through:
71
+
72
+ `to:` and `where:` filter where the step **arrives**; the walk still passes through other nodes on the way:
73
+
74
+ ```ruby
75
+ # Every bar anywhere under Washington, but walk through every locale to find them.
76
+ washington.traverse(:contains, depth: 0..).traverse(:has_venue, where: Venue.where(kind: 'bar'))
77
+
78
+ # The same with a Hash, because the step reaches one model.
79
+ washington.traverse(:contains, depth: 0..).traverse(:has_venue, where: { kind: 'bar' })
80
+
81
+ # A step whose edges reach several models: arrive only at events.
82
+ venue.traverse(:rolls_up, depth: 1.., to: Event)
83
+ ```
84
+
85
+ `through:` filters every node **on the way** (Cypher's `all(n IN nodes(p) WHERE ...)`). A node outside the relation
86
+ stops the walk there:
87
+
88
+ ```ruby
89
+ # Only descend through active locales; a retired county hides everything under it.
90
+ washington.traverse(:contains, depth: 1.., through: Locale.where(retired_at: nil))
91
+ ```
92
+
93
+ ### edge_where:
94
+
95
+ Filters the edge rows themselves:
96
+
97
+ ```ruby
98
+ event.traverse(:billed, edge_where: { role: 'headliner' })
99
+ person.traverse(:member_of, edge_where: -> { where(ended_at: nil) })
100
+ ```
101
+
102
+ Like a missing property in Cypher, an edge kept in a table without the filter's columns doesn't match it, so a union
103
+ edge is narrowed to the parts that have the column. SQL edges match no filter.
104
+
105
+ ## Starting elsewhere
106
+
107
+ ```ruby
108
+ GraphQuery.from(Venue.where(kind: 'bar')) # any relation, record or model
109
+ GraphQuery.from_pairs([[Venue, venue_id], ['Person', person_id]]) # nodes of several models at once
110
+ GraphQuery.from_query(other_query) # the nodes another walk reached
111
+ Locale.where(...).graph # a Query that hasn't moved yet; chain .out/.inbound
112
+ ```
113
+
114
+ ## Errors
115
+
116
+ - `GraphQuery::NoEdges`: the step names edges that don't leave the nodes it starts on (`no has_venue (out) from
117
+ Person`), or its `to:` can't be reached. A step with `depth: 0..` from nodes with no such edges isn't an error: it
118
+ keeps the nodes it started on.
119
+ - `GraphQuery::AmbiguousResult`: you asked for a relation, but the walk reaches several models. Name one, add `to:`,
120
+ or use `pairs` / `records` / `polymorphic`.
121
+ - `ArgumentError`: a bad `depth:` or `direction:`.
@@ -0,0 +1,106 @@
1
+ # Results
2
+
3
+ A walk doesn't run until you ask for something. What you can ask for:
4
+
5
+ | Method | Gives |
6
+ | --- | --- |
7
+ | relation methods (`where`, `order`, `pluck`, `count`, `each`, `find_each`, `exists?`, ...) | the reached nodes, as a relation (the walk must reach one model) |
8
+ | `to_relation(Model)` / `nodes(Model)` | the reached nodes of one model, as a relation |
9
+ | `with_depth(Model)` | that relation plus `graph_depth`, the fewest hops in the last step |
10
+ | `pairs` | `[[type, id], ...]` for every node reached, whatever its model |
11
+ | `records` | every node reached, loaded, whatever its model |
12
+ | `polymorphic(scope, :name)` | rows of `scope` whose polymorphic association points at a reached node |
13
+ | `by_origin(Model)` | `{start id => [reached records]}` |
14
+ | `origin_pairs(Model)` | `[[start id, reached id], ...]`, unloaded |
15
+ | `paths` | every simple path, `[[type, id], ...]` from start to end |
16
+ | `to_sql(origin:, depth:, path:)` | the statement |
17
+ | `types` | the model names the walk can end on |
18
+
19
+ ## Relations
20
+
21
+ When the last step reaches one model, a Query acts as a relation of it:
22
+
23
+ ```ruby
24
+ venues = washington.traverse(:contains, depth: 0..).traverse(:has_venue)
25
+ venues.where(kind: 'bar').order(:name).limit(10).to_a
26
+ venues.count
27
+ venues.pluck(:id)
28
+ venues.includes(:locale).find_each { ... }
29
+ ```
30
+
31
+ Under the hood that's `Venue.where(id: <the walk>)`, so it composes with scopes, joins, `merge` and pagination. If the
32
+ walk can reach several models, pick one: `query.to_relation(Event)`.
33
+
34
+ ## Depth
35
+
36
+ `with_depth` joins the walk and selects each node's hop count in the last step as `graph_depth`:
37
+
38
+ ```ruby
39
+ seattle.traverse(:within, depth: 1..).with_depth
40
+ .reorder(Arel.sql('graph_query_nodes.depth DESC')) # outermost first
41
+ .pluck(:id)
42
+ ```
43
+
44
+ Order by `graph_query_nodes.depth` rather than `graph_depth`: the alias doesn't survive `pluck`.
45
+
46
+ ## Several models
47
+
48
+ ```ruby
49
+ walk = venue.traverse(:rolls_up, depth: 1..) # events and event series
50
+ walk.types # => ["Event", "EventSeries"]
51
+ walk.pairs # => [["Event", "4c1..."], ["EventSeries", "9ae..."], ...]
52
+ walk.records # => [#<Event ...>, #<EventSeries ...>, ...] (one query per model)
53
+ ```
54
+
55
+ ## Roll-ups: `polymorphic`
56
+
57
+ Given a scope of rows with a polymorphic association, keep those pointing at any node the walk reaches. This is how
58
+ "everything linked to anything under this venue" works:
59
+
60
+ ```ruby
61
+ venue.traverse(:rolls_up, depth: 0..)
62
+ .polymorphic(EntityLink.where(audience_id:), :target) # target_type / target_id
63
+ .order(created_at: :desc)
64
+ ```
65
+
66
+ The association's `foreign_type` / `foreign_key` are used if it's declared; otherwise `name_type` / `name_id`.
67
+
68
+ ## Batching many starts: `by_origin`
69
+
70
+ Walk from many nodes in one statement and group what each reached, for a GraphQL dataloader:
71
+
72
+ ```ruby
73
+ class LocalPeopleSource < GraphQL::Dataloader::Source
74
+ def fetch(locale_ids)
75
+ found = Locale.where(id: locale_ids).traverse(:contains, depth: 0..).traverse(:features).by_origin(Person)
76
+ locale_ids.map { found.fetch(it, []) }
77
+ end
78
+ end
79
+ ```
80
+
81
+ `origin_pairs` gives the same as `[[locale_id, person_id], ...]` without loading anything.
82
+
83
+ ## Paths
84
+
85
+ ```ruby
86
+ GraphQuery.from(person).traverse(:knows, depth: 1..3).paths
87
+ # => [[["Person", "a"], ["Person", "b"]], [["Person", "a"], ["Person", "b"], ["Person", "c"]], ...]
88
+ ```
89
+
90
+ Paths never revisit a node. Rows are routes, not nodes, so their number can grow fast: use `paths` to show a route,
91
+ not on big graphs.
92
+
93
+ ## SQL
94
+
95
+ ```ruby
96
+ query.to_sql # node_type, node_id
97
+ query.to_sql(origin: true) # + origin_type, origin_id (the start node each row came from)
98
+ query.to_sql(depth: true) # + depth (fewest hops in the last step)
99
+ query.to_sql(path: true) # + path ('Type:id' text[])
100
+ ```
101
+
102
+ Use it for `EXPLAIN ANALYZE`, or to join a walk by hand:
103
+
104
+ ```ruby
105
+ Event.joins("JOIN (#{walk.to_sql}) g ON g.node_type = 'Event' AND g.node_id = events.id")
106
+ ```