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 +7 -0
- data/CHANGELOG.md +33 -0
- data/LICENSE.txt +21 -0
- data/README.md +96 -0
- data/docs/01-getting-started.md +82 -0
- data/docs/02-declaring-edges.md +134 -0
- data/docs/03-walking.md +121 -0
- data/docs/04-results.md +106 -0
- data/docs/05-patterns.md +80 -0
- data/docs/06-cypher.md +94 -0
- data/docs/07-writes.md +81 -0
- data/docs/08-graphql.md +118 -0
- data/docs/09-internals.md +108 -0
- data/docs/10-reference.md +114 -0
- data/lib/graph_query/age.rb +31 -0
- data/lib/graph_query/associations.rb +73 -0
- data/lib/graph_query/compiler.rb +224 -0
- data/lib/graph_query/cypher.rb +378 -0
- data/lib/graph_query/edge.rb +117 -0
- data/lib/graph_query/graphql.rb +329 -0
- data/lib/graph_query/match.rb +119 -0
- data/lib/graph_query/model.rb +97 -0
- data/lib/graph_query/mutation.rb +82 -0
- data/lib/graph_query/pattern.rb +104 -0
- data/lib/graph_query/query.rb +168 -0
- data/lib/graph_query/registry.rb +52 -0
- data/lib/graph_query/syntax.rb +85 -0
- data/lib/graph_query/transaction.rb +140 -0
- data/lib/graph_query/version.rb +5 -0
- data/lib/graph_query.rb +123 -0
- data/rbi/graph_query.rbi +356 -0
- data/sig/graph_query.rbs +231 -0
- metadata +106 -0
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
|
+
[](https://github.com/lwm-luminx/graph_query/actions/workflows/ci.yml)
|
|
4
|
+
[](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.
|
data/docs/03-walking.md
ADDED
|
@@ -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:`.
|
data/docs/04-results.md
ADDED
|
@@ -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
|
+
```
|