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
data/docs/05-patterns.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Patterns
|
|
2
|
+
|
|
3
|
+
`GraphQuery.match(pattern, **bindings)` runs a linear Cypher-style pattern with Ruby bindings. For a whole Cypher
|
|
4
|
+
query as text (`MATCH ... WHERE ... RETURN`), see [Cypher queries](#cypher). It builds the same steps as `traverse`, so
|
|
5
|
+
everything about walks applies.
|
|
6
|
+
|
|
7
|
+
```ruby
|
|
8
|
+
GraphQuery.match(
|
|
9
|
+
'(s:Locale)-[:contains*0..]->()-[:has_venue]->(v:Venue)-[:hosts]->(e:Event)<-[:billed_on]-(p:Person)',
|
|
10
|
+
s: Locale.where(name: 'Washington'),
|
|
11
|
+
e: Event.upcoming
|
|
12
|
+
).nodes(:v) # venues in Washington where someone is billed on an upcoming event
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
From a scope, the scope binds the first node:
|
|
16
|
+
|
|
17
|
+
```ruby
|
|
18
|
+
Locale.where(name: 'Seattle').graph_match('(l)-[:contains*0..]->()-[:has_venue]->(v:Venue)')
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Syntax
|
|
22
|
+
|
|
23
|
+
| Part | Means |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `(v)`, `(v:Venue)`, `(:Venue|Event)`, `()` | a node, with an optional variable and labels (models) |
|
|
26
|
+
| `(v:Venue {kind: 'bar', city: $city})` | a node whose columns match a property map |
|
|
27
|
+
| `-[:billed_on {role: 'headliner'}]->` | edges whose rows match a property map |
|
|
28
|
+
| `-[:has_venue]->` | one hop out along `has_venue` |
|
|
29
|
+
| `<-[:hosts]-` | one hop in (walk `hosts` backwards) |
|
|
30
|
+
| `-[:knows]-` | one hop either way |
|
|
31
|
+
| `-[r:billed_on|hosts]->` | either edge, with a variable to bind conditions to |
|
|
32
|
+
| `-->`, `<--`, `--` | any edge, one hop |
|
|
33
|
+
| `*` | one or more hops |
|
|
34
|
+
| `*2` | exactly two |
|
|
35
|
+
| `*1..3`, `*..3` | one to three |
|
|
36
|
+
| `*0..` | zero or more (the node itself too) |
|
|
37
|
+
|
|
38
|
+
Names may be written as in Cypher: `CONTAINS` and `hasVenue` match `:contains` and `:has_venue`. Labels are model
|
|
39
|
+
names (`event_series` and `EventSeries` both work).
|
|
40
|
+
|
|
41
|
+
## Bindings
|
|
42
|
+
|
|
43
|
+
There's no `WHERE` or `RETURN` text. Bind variables instead:
|
|
44
|
+
|
|
45
|
+
- **A node variable** to a relation (or record, or model): the node must be in it. `v: Venue.where(kind: 'bar')`.
|
|
46
|
+
- **A relationship variable** to a Hash or scope Proc: an `edge_where:` on that step.
|
|
47
|
+
`GraphQuery.match('(e:Event)<-[b:billed_on]-(p:Person)', e: event, b: { role: 'headliner' })`.
|
|
48
|
+
|
|
49
|
+
Property maps do the same job inline. Their values are literals (`'text'`, `42`, `1.5`, `true`, `null`, `[...]`) or
|
|
50
|
+
`$params`, read from `params:`:
|
|
51
|
+
|
|
52
|
+
```ruby
|
|
53
|
+
GraphQuery.match("(s:Locale {name: $state})-[:contains*0..]->()-[:has_venue]->(v:Venue {kind: 'bar'})",
|
|
54
|
+
params: { state: 'Washington' })
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
A node with a property map needs one label or a binding, so graph_query knows which table the columns are in.
|
|
58
|
+
|
|
59
|
+
The first node must be bound or have exactly one label (`(s:Locale)` alone starts from every locale).
|
|
60
|
+
|
|
61
|
+
## Results
|
|
62
|
+
|
|
63
|
+
A Match acts as a relation of the **last** node's matches, like a Query. For another node, use `nodes(:var)`:
|
|
64
|
+
|
|
65
|
+
```ruby
|
|
66
|
+
match = GraphQuery.match('(s:Locale)-[:contains*0..]->(l)-[:has_venue]->(v:Venue)', s: washington,
|
|
67
|
+
v: Venue.where(kind: 'bar'))
|
|
68
|
+
match.count # bars
|
|
69
|
+
match.nodes(:l) # only the locales that have a bar under them
|
|
70
|
+
match.paths # each full route
|
|
71
|
+
match.query # the underlying GraphQuery::Query
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
A variable in the middle counts only nodes that lie on a full match: graph_query walks forward to that node, walks
|
|
75
|
+
back from the end of every full match to it, and keeps the overlap.
|
|
76
|
+
|
|
77
|
+
## Beyond one path
|
|
78
|
+
|
|
79
|
+
More than one path, `WHERE`, `RETURN`, `ORDER BY`, `SKIP` and `LIMIT`: [Cypher queries](#cypher) take those. For
|
|
80
|
+
anything else, chain `traverse` steps or use `from_query` to start a second walk from the first one's result.
|
data/docs/06-cypher.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Cypher queries
|
|
2
|
+
|
|
3
|
+
`GraphQuery.cypher(query, **params)` runs a read-only Cypher query on the same walker as `traverse`: no Apache AGE, no
|
|
4
|
+
extension, one `WITH RECURSIVE` per path.
|
|
5
|
+
|
|
6
|
+
```ruby
|
|
7
|
+
GraphQuery.cypher(<<~CYPHER, state: 'Washington', limit: 10)
|
|
8
|
+
MATCH (s:Locale {name: $state})-[:contains*0..]->(c:Locale)-[:has_venue]->(v:Venue)
|
|
9
|
+
WHERE c.kind = 'city' AND v.name STARTS WITH 'The' AND NOT v.closed
|
|
10
|
+
RETURN v
|
|
11
|
+
ORDER BY v.name
|
|
12
|
+
LIMIT $limit
|
|
13
|
+
CYPHER
|
|
14
|
+
# => a Venue relation, still chainable
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Clauses
|
|
18
|
+
|
|
19
|
+
| Clause | Takes |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| `MATCH` | one or more [patterns](#patterns), comma-separated or in several `MATCH` clauses |
|
|
22
|
+
| `WHERE` | conditions on node properties (after any `MATCH`; several are ANDed) |
|
|
23
|
+
| `RETURN` | `v`, `v.name, v.kind` (with optional `AS`), `count(*)`, `count(v)`, `count(DISTINCT v)`; `DISTINCT` |
|
|
24
|
+
| `ORDER BY` | `v.name`, `toLower(v.name) DESC`, several |
|
|
25
|
+
| `SKIP`, `LIMIT` | a whole number or a `$param` |
|
|
26
|
+
|
|
27
|
+
Labels are model names; relationship types are edge names (`HAS_VENUE` and `hasVenue` both match `:has_venue`).
|
|
28
|
+
Properties are the model's columns. Keywords are case-insensitive, `//` starts a comment, and a trailing `;` is fine.
|
|
29
|
+
|
|
30
|
+
## WHERE
|
|
31
|
+
|
|
32
|
+
| Condition | SQL |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| `v.x = 1`, `<>`, `!=`, `<`, `<=`, `>`, `>=` | comparisons (`= null` is `IS NULL`) |
|
|
35
|
+
| `v.x IS NULL`, `v.x IS NOT NULL` | null tests |
|
|
36
|
+
| `v.x IN ['a', 'b']`, `v.x NOT IN $list` | `IN` |
|
|
37
|
+
| `v.x STARTS WITH 'a'`, `ENDS WITH`, `CONTAINS` | `LIKE`, with `%` and `_` escaped |
|
|
38
|
+
| `v.x =~ 'Sea.*'` | a PostgreSQL regular expression on the whole value |
|
|
39
|
+
| `toLower(v.x) = 'bar'`, `toUpper(...)` | `LOWER()` / `UPPER()` |
|
|
40
|
+
| `v.open` | `v.open = true` |
|
|
41
|
+
| `v.x = v.y` | two columns of the same node |
|
|
42
|
+
| `AND`, `OR`, `XOR`, `NOT`, `( ... )` | as written |
|
|
43
|
+
|
|
44
|
+
Each condition is about **one variable**. graph_query turns each variable's conditions into a relation and walks
|
|
45
|
+
through it, so conditions on nodes in the middle of a path narrow the walk as it goes:
|
|
46
|
+
|
|
47
|
+
```cypher
|
|
48
|
+
MATCH (s:Locale)-[:contains*0..]->(c:Locale)-[:has_venue]->(v:Venue)
|
|
49
|
+
WHERE s.name = 'USA' AND c.kind = 'city' AND (v.name STARTS WITH 'E' OR v.name ENDS WITH 'sh')
|
|
50
|
+
RETURN v
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
A condition comparing two variables (`a.name = b.name`) raises `GraphQuery::UnsupportedCypher`.
|
|
54
|
+
|
|
55
|
+
## RETURN
|
|
56
|
+
|
|
57
|
+
| RETURN | Gives |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `v` | a relation of `v`'s nodes (lazy, chainable) |
|
|
60
|
+
| `v.name` | `pluck(:name)`: `['Eagle', 'Globe']` |
|
|
61
|
+
| `v.name, v.kind` | `pluck(:name, :kind)`: `[['Eagle', 'bar'], ...]` |
|
|
62
|
+
| `DISTINCT v.kind` | distinct values |
|
|
63
|
+
| `count(*)`, `count(v)`, `count(DISTINCT v)` | an Integer: how many distinct nodes |
|
|
64
|
+
|
|
65
|
+
Return one variable. A walk finds the nodes that can be reached, not every combination of nodes along the way, so
|
|
66
|
+
`RETURN a, b` raises `UnsupportedCypher`; return one and walk again from it if you need the other.
|
|
67
|
+
|
|
68
|
+
## Several patterns
|
|
69
|
+
|
|
70
|
+
Patterns that share a variable are joined on it:
|
|
71
|
+
|
|
72
|
+
```cypher
|
|
73
|
+
MATCH (p:Person)-[:billed_on]->(e:Event), (v:Venue)-[:hosts]->(e)
|
|
74
|
+
MATCH (:Locale {name: 'Oregon'})-[:contains*0..]->()-[:has_venue]->(v)
|
|
75
|
+
RETURN e
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Each pattern narrows the shared variables to the nodes it can match, and the narrowing repeats once per pattern so it
|
|
79
|
+
carries through chains of patterns. This is exact when the patterns form a tree (joined one variable at a time). When
|
|
80
|
+
two patterns share two variables, each variable is narrowed on its own, so a pair that matches separately but not
|
|
81
|
+
together still passes.
|
|
82
|
+
|
|
83
|
+
## Parameters
|
|
84
|
+
|
|
85
|
+
`$name` reads the keyword arguments: in property maps, `WHERE`, `IN`, `SKIP` and `LIMIT`. Values are always passed to
|
|
86
|
+
SQL as quoted values, never as SQL text. A missing parameter raises `GraphQuery::PatternError`.
|
|
87
|
+
|
|
88
|
+
## Not supported
|
|
89
|
+
|
|
90
|
+
Writing clauses (`CREATE`, `MERGE`, `SET`, `DELETE`), `OPTIONAL MATCH`, `WITH`, `UNWIND`, `UNION`, aggregation other
|
|
91
|
+
than `count`, path variables (`p = (a)-->(b)`), and returning several variables. Each raises a `PatternError` or
|
|
92
|
+
`UnsupportedCypher` that names what it met.
|
|
93
|
+
|
|
94
|
+
If a database has Apache AGE, `GraphQuery::Age.cypher` passes full Cypher through to it (see [How it runs](#internals)).
|
data/docs/07-writes.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Writing edges
|
|
2
|
+
|
|
3
|
+
The edges you declare to read the graph can also write it. `GraphQuery.transaction` opens one database transaction
|
|
4
|
+
and gives you a `GraphQuery::Transaction` that links and unlinks by edge name:
|
|
5
|
+
|
|
6
|
+
```ruby
|
|
7
|
+
GraphQuery.transaction do |graph|
|
|
8
|
+
hill = graph.create(Locale, name: 'Capitol Hill')
|
|
9
|
+
graph.link(seattle, :contains, hill) # sets locales.parent_id
|
|
10
|
+
graph.link(northwest, :contains, hill, via: LocaleGrouping, # creates a join row
|
|
11
|
+
attributes: { role: 'core' })
|
|
12
|
+
graph.relink(hill, :has_venue, eagle, from: downtown) # moves the venue
|
|
13
|
+
graph.unlink(seattle, :has_venue, closed_bar)
|
|
14
|
+
end
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Where a write lands
|
|
18
|
+
|
|
19
|
+
An edge is written where it's kept:
|
|
20
|
+
|
|
21
|
+
| The edge is kept | `link` | `unlink` |
|
|
22
|
+
| --- | --- | --- |
|
|
23
|
+
| on the target's row (`has_many`, `has_one`) | sets the target's foreign key | clears it |
|
|
24
|
+
| on the source's row (`belongs_to`) | sets the source's foreign key | clears it |
|
|
25
|
+
| in a join model (`has_many :through`, `through:`) | creates a join row with the edge's Hash `where:` conditions and `attributes:` | destroys the matching rows |
|
|
26
|
+
|
|
27
|
+
Linking an edge that's already there, or unlinking one that isn't, changes nothing. SQL and computed edges can't be
|
|
28
|
+
written.
|
|
29
|
+
|
|
30
|
+
When several edges share a name between the same two models (a `has_many` and a join model, say), pass `via:` with
|
|
31
|
+
the model that holds the one you mean. Without it the transaction raises `GraphQuery::AmbiguousResult`.
|
|
32
|
+
|
|
33
|
+
## Methods
|
|
34
|
+
|
|
35
|
+
| Method | |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| `link(from, name, to, via: nil, attributes: {})` | add the edge |
|
|
38
|
+
| `unlink(from, name, to, via: nil)` | remove it |
|
|
39
|
+
| `relink(new_from, name, to, from:, via: nil, attributes: {})` | unlink from `from:`, link from `new_from` |
|
|
40
|
+
| `linked?(from, name, to, via: nil)` | whether the edge is there |
|
|
41
|
+
| `create(model, **attributes)`, `update(record, **attributes)`, `destroy(record)` | write nodes in the same transaction |
|
|
42
|
+
| `changes` | what was written, in order: `Change(action, edge, from, to, record)` |
|
|
43
|
+
|
|
44
|
+
Rows are saved with `save!` and `destroy!`, so validations and callbacks run. Any exception rolls every write back.
|
|
45
|
+
`GraphQuery.transaction` nests inside an outer transaction as a savepoint.
|
|
46
|
+
|
|
47
|
+
## Graph mutations
|
|
48
|
+
|
|
49
|
+
A graph mutation is a model method that writes the graph, marked so that it runs in a transaction and can be
|
|
50
|
+
exposed to GraphQL. Put `graph_mutation` on the line before the `def`:
|
|
51
|
+
|
|
52
|
+
```ruby
|
|
53
|
+
class Locale < ApplicationRecord
|
|
54
|
+
graph_mutation arguments: { child: Locale, role: String }, description: 'Make child a member of this locale.'
|
|
55
|
+
def adopt(child:, role: nil, graph:)
|
|
56
|
+
graph.link(self, :contains, child, via: LocaleGrouping, attributes: { role: })
|
|
57
|
+
self
|
|
58
|
+
end
|
|
59
|
+
|
|
60
|
+
graph_mutation def close = update!(closed_at: Time.current) && self # or in front of it, with no options
|
|
61
|
+
|
|
62
|
+
graph_mutation arguments: { venues: [Venue] }, returns: Venue
|
|
63
|
+
def take_venues(venues:, graph:)
|
|
64
|
+
venues.each { graph.relink(self, :has_venue, it, from: it.locale) }
|
|
65
|
+
venues.first
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
northwest.adopt(child: seattle) # runs in GraphQuery.transaction; graph: is filled in
|
|
70
|
+
Locale.graph_mutations # => { adopt: #<GraphQuery::Mutation Locale#adopt>, take_venues: ... }
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- The method runs inside `GraphQuery.transaction`. If it takes a `graph:` keyword, it's given the transaction.
|
|
74
|
+
- `arguments:` types each keyword for GraphQL. A model takes an ID, `[Model]` takes a list of IDs,
|
|
75
|
+
and `String`, `Integer`, `Float`, `:boolean`, `:id`, `:json`, `Date`, `Time` or a GraphQL type pass straight
|
|
76
|
+
through. Required keywords become required arguments.
|
|
77
|
+
- `returns:` types the result. The default is the model.
|
|
78
|
+
- Models may be given as classes or as names (`'Venue'`); a name avoids loading a model the class body can't see yet.
|
|
79
|
+
- Calling the method from Ruby works the same way, so the same write path backs a console, a job and the API.
|
|
80
|
+
|
|
81
|
+
See [GraphQL](#graphql) for turning these into mutation fields.
|
data/docs/08-graphql.md
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# GraphQL
|
|
2
|
+
|
|
3
|
+
`require 'graph_query/graphql'` adds [graphql-ruby](https://graphql-ruby.org) support (graphql 2.3 or later; the gem
|
|
4
|
+
doesn't depend on it otherwise). Declared edges back fields, and graph mutations back mutation fields.
|
|
5
|
+
|
|
6
|
+
## Fields backed by walks
|
|
7
|
+
|
|
8
|
+
Extend an object type with `GraphQuery::GraphQL::Fields`, then declare fields by edge, pattern or block:
|
|
9
|
+
|
|
10
|
+
```ruby
|
|
11
|
+
class Types::LocaleType < Types::BaseObject
|
|
12
|
+
extend GraphQuery::GraphQL::Fields
|
|
13
|
+
|
|
14
|
+
graph_field :children, [Types::LocaleType], edge: :contains # one hop
|
|
15
|
+
graph_field :venues, [Types::VenueType], edge: %i[contains has_venue], depth: 0.. # contains*0.. then has_venue
|
|
16
|
+
graph_field :bars, Types::VenueType.connection_type, # paginated
|
|
17
|
+
pattern: '()-[:contains*0..]->()-[:has_venue]->(v:Venue)',
|
|
18
|
+
scope: ->(venues, context) { venues.where(kind: 'bar').order(:name) }
|
|
19
|
+
graph_field(:events, [Types::EventType]) do |start| # anything a Query can do
|
|
20
|
+
start.traverse(:contains, depth: 0..).traverse(:has_venue).traverse(:hosts, edge_where: { cancelled: false })
|
|
21
|
+
end
|
|
22
|
+
end
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
| Option | |
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| `edge:` | an edge name, or several walked in turn (`depth:` and the other walk options apply to all but the last) |
|
|
28
|
+
| `pattern:` | a [pattern](#patterns) whose first node is the object; the field returns the last node |
|
|
29
|
+
| a block | given `GraphQuery.from(object)`, returns a Query |
|
|
30
|
+
| `depth:`, `direction:`, `to:`, `through:`, `edge_where:` | as in [walking](#walking) |
|
|
31
|
+
| `scope:` | `->(relation, context)` to filter, order or authorize the result |
|
|
32
|
+
| `model:` | the result's model, when the walk can reach several |
|
|
33
|
+
|
|
34
|
+
A list field is **batched**. graph_query loads it through `GraphQL::Dataloader`, so 50 locales asking for their
|
|
35
|
+
venues run one walk from all 50 (with `origin_pairs`) and one load, not 50 of each. Add `use GraphQL::Dataloader` to
|
|
36
|
+
the schema. A connection field returns a relation per object, so graphql-ruby paginates it in SQL.
|
|
37
|
+
|
|
38
|
+
## A field per declared edge
|
|
39
|
+
|
|
40
|
+
`graph_edges` adds a list field for every edge a model declares, one hop out:
|
|
41
|
+
|
|
42
|
+
```ruby
|
|
43
|
+
class Types::LocaleType < Types::BaseObject
|
|
44
|
+
extend GraphQuery::GraphQL::Fields
|
|
45
|
+
graph_edges Locale, only: %i[within rolls_up] # within: [LocaleType], rolls_up_venues, rolls_up_events ...
|
|
46
|
+
end
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
A field is named after its edge, or `edge_targets` when one edge name reaches several models. `except:` leaves edges
|
|
50
|
+
out, and `scope:` applies to every field.
|
|
51
|
+
|
|
52
|
+
Types are found by model name through `GraphQuery::GraphQL.type_for`. The default returns `"Types::<Model>Type"`,
|
|
53
|
+
which graphql-ruby resolves lazily, so a type can list edges back to itself. Set your own when the types are named
|
|
54
|
+
differently:
|
|
55
|
+
|
|
56
|
+
```ruby
|
|
57
|
+
GraphQuery::GraphQL.type_for = ->(model_name) { "Types::#{model_name}Object" }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Mutations from graph mutations
|
|
61
|
+
|
|
62
|
+
Extend the mutation type with `GraphQuery::GraphQL::MutationFields` and name the models:
|
|
63
|
+
|
|
64
|
+
```ruby
|
|
65
|
+
class Types::MutationType < Types::BaseObject
|
|
66
|
+
extend GraphQuery::GraphQL::MutationFields
|
|
67
|
+
graph_mutations Locale, Venue # localeAdopt, localeTakeVenues, ...
|
|
68
|
+
end
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Each [graph mutation](#writes) becomes a Relay-style mutation named `<model>_<method>`:
|
|
72
|
+
|
|
73
|
+
```graphql
|
|
74
|
+
mutation {
|
|
75
|
+
localeAdopt(input: { id: "...", childId: "...", role: "core" }) { result { name } errors }
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
- `id` finds the record to call the method on. Model arguments become `childId` / `venueIds` and are loaded through
|
|
80
|
+
`GraphQuery::GraphQL.record_for`. By default that's the schema's `object_from_id`, falling back to `Model.find`.
|
|
81
|
+
- `result` is what the method returns, typed by `returns:`. `errors` lists messages.
|
|
82
|
+
- The whole mutation runs in one transaction. A validation failure, a `GraphQuery::Error` or a returned `errors`
|
|
83
|
+
rolls it back and comes back in `errors`.
|
|
84
|
+
- `only:` and `except:` pick methods, and `base:` sets the mutation base class.
|
|
85
|
+
|
|
86
|
+
## Other mutations
|
|
87
|
+
|
|
88
|
+
For a mutation written by hand, include `GraphQuery::GraphQL::TransactionalMutation`. `resolve` then runs in one
|
|
89
|
+
transaction with `graph` open:
|
|
90
|
+
|
|
91
|
+
```ruby
|
|
92
|
+
class Mutations::MoveVenue < Types::BaseMutation
|
|
93
|
+
include GraphQuery::GraphQL::TransactionalMutation
|
|
94
|
+
argument :venue_id, ID
|
|
95
|
+
argument :locale_id, ID
|
|
96
|
+
field :venue, Types::VenueType
|
|
97
|
+
field :errors, [String], null: false
|
|
98
|
+
|
|
99
|
+
def resolve(venue_id:, locale_id:)
|
|
100
|
+
venue = Venue.find(venue_id)
|
|
101
|
+
graph.relink(Locale.find(locale_id), :has_venue, venue, from: venue.locale)
|
|
102
|
+
{ venue: venue.reload, errors: [] }
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Without an `errors` field, failures are raised as `GraphQL::ExecutionError`.
|
|
108
|
+
|
|
109
|
+
To link or unlink one edge by ID, `edge_mutation` builds the whole class:
|
|
110
|
+
|
|
111
|
+
```ruby
|
|
112
|
+
field :add_venue, mutation: GraphQuery::GraphQL.edge_mutation(Locale, :has_venue, Venue)
|
|
113
|
+
field :remove_venue, mutation: GraphQuery::GraphQL.edge_mutation(Locale, :has_venue, Venue, action: :unlink)
|
|
114
|
+
# addVenue(input: { fromId: "...", toId: "..." }) { changed from { name } to { name } errors }
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Authorize these the way you authorize any graphql-ruby mutation (`ready?`, `authorized?`, or the base class you pass
|
|
118
|
+
as `base:`).
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# How it runs
|
|
2
|
+
|
|
3
|
+
## One statement per walk
|
|
4
|
+
|
|
5
|
+
Each walk compiles to one `WITH RECURSIVE` statement. Node sets are CTEs: `g0` is the start, `gN` the nodes after step
|
|
6
|
+
N, each with columns `(node_type, node_id)` plus whatever the result needs (`origin_type`/`origin_id`, `depth`, `path`).
|
|
7
|
+
|
|
8
|
+
This walk:
|
|
9
|
+
|
|
10
|
+
```ruby
|
|
11
|
+
Locale.where(name: 'Seattle').traverse(:contains, depth: 0..).traverse(:features)
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
compiles to (reformatted):
|
|
15
|
+
|
|
16
|
+
```sql
|
|
17
|
+
WITH RECURSIVE
|
|
18
|
+
g0 AS (
|
|
19
|
+
SELECT DISTINCT node_type, node_id FROM (
|
|
20
|
+
SELECT 'Locale'::text AS node_type, start_rows."id" AS node_id
|
|
21
|
+
FROM (SELECT "locales"."id" FROM "locales" WHERE "locales"."name" = 'Seattle') start_rows
|
|
22
|
+
) graph_query_start),
|
|
23
|
+
g1_walk(node_type, node_id) AS (
|
|
24
|
+
SELECT p.node_type, p.node_id FROM g0 p
|
|
25
|
+
UNION
|
|
26
|
+
SELECT e.to_type, e.to_id FROM g1_walk w
|
|
27
|
+
CROSS JOIN LATERAL (
|
|
28
|
+
(SELECT 'Locale'::text AS from_type, edge_rows.source_id AS from_id,
|
|
29
|
+
'Locale'::text AS to_type, edge_rows.target_id AS to_id
|
|
30
|
+
FROM (SELECT parent_id AS source_id, id AS target_id FROM locales
|
|
31
|
+
WHERE parent_id IS NOT NULL AND id IS NOT NULL) edge_rows
|
|
32
|
+
WHERE edge_rows.source_id = w.node_id AND w.node_type = 'Locale')
|
|
33
|
+
UNION ALL
|
|
34
|
+
(SELECT 'Locale', edge_rows.source_id, 'Locale', edge_rows.target_id
|
|
35
|
+
FROM (SELECT super_locale_id AS source_id, member_locale_id AS target_id FROM locale_groupings
|
|
36
|
+
WHERE super_locale_id IS NOT NULL AND member_locale_id IS NOT NULL) edge_rows
|
|
37
|
+
WHERE edge_rows.source_id = w.node_id AND w.node_type = 'Locale')
|
|
38
|
+
) e),
|
|
39
|
+
g1(node_type, node_id) AS (SELECT DISTINCT * FROM g1_walk x),
|
|
40
|
+
g2(node_type, node_id) AS (
|
|
41
|
+
SELECT DISTINCT * FROM (
|
|
42
|
+
SELECT e.to_type, e.to_id FROM g1 p
|
|
43
|
+
CROSS JOIN LATERAL (
|
|
44
|
+
(SELECT 'Locale', edge_rows.source_id, 'Person', edge_rows.target_id
|
|
45
|
+
FROM (SELECT locale_id AS source_id, person_id AS target_id FROM person_locales
|
|
46
|
+
WHERE locale_id IS NOT NULL AND person_id IS NOT NULL) edge_rows
|
|
47
|
+
WHERE edge_rows.source_id = p.node_id AND p.node_type = 'Locale')
|
|
48
|
+
) e) x)
|
|
49
|
+
SELECT * FROM g2
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Step shapes
|
|
53
|
+
|
|
54
|
+
The compiler picks the cheapest shape a step allows:
|
|
55
|
+
|
|
56
|
+
| Step | Shape |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| no edge to follow, `depth: 0..` | keep the nodes it started on |
|
|
59
|
+
| `depth: 1` or `0..1` | one join |
|
|
60
|
+
| `depth: 1..` or `0..` | a recursive set with `UNION`: it ends when nothing new turns up, so cycles end it |
|
|
61
|
+
| `depth: 1..3`, `2..`, or anything needing `with_depth` | a hop count on each row, stopping at the bound (or `max_depth`), then grouped to the fewest hops |
|
|
62
|
+
| `paths` | `UNION ALL` of routes, each carrying a `text[]` of `'Type:id'` and refusing to revisit a node |
|
|
63
|
+
|
|
64
|
+
## Why LATERAL
|
|
65
|
+
|
|
66
|
+
Each hop joins the edges through `CROSS JOIN LATERAL`, with the `source_id = node_id` condition inside each branch of
|
|
67
|
+
the edge union. That lets PostgreSQL read each edge table through its index on the column that points back, one row
|
|
68
|
+
of the frontier at a time, instead of scanning and hashing whole tables on every iteration. On a 200,000-locale tree, a
|
|
69
|
+
subtree walk went from 62 ms to 8 ms with this change. Index the foreign key columns your edges read (Rails does for
|
|
70
|
+
`references`).
|
|
71
|
+
|
|
72
|
+
## Which edges a step uses
|
|
73
|
+
|
|
74
|
+
Before compiling, a step works out which edges it may follow: those leaving the models it starts on and, for a
|
|
75
|
+
multi-hop step, those leaving every model it can reach, until no new model turns up. A step over `:rolls_up` from a
|
|
76
|
+
Locale therefore also follows Venue's and EventSeries' `:rolls_up` edges. Only those edges' tables appear in the SQL.
|
|
77
|
+
|
|
78
|
+
## Limits
|
|
79
|
+
|
|
80
|
+
- **Node ids share a type** within a walk (all uuid, or all bigint).
|
|
81
|
+
- **`max_depth`** (32) caps unbounded steps that count hops. Plain closures (`0..`, `1..`) have no cap; cycles end them.
|
|
82
|
+
- **`paths`** grows with the number of routes, not nodes.
|
|
83
|
+
- **No branching patterns.** Chain steps or start a second walk with `from_query`.
|
|
84
|
+
- **SQL edges** don't take `edge_where:`, and only use indexes if the planner can push the condition into them.
|
|
85
|
+
|
|
86
|
+
## Apache AGE
|
|
87
|
+
|
|
88
|
+
Where a database has Apache AGE, `GraphQuery::Age` passes real Cypher through:
|
|
89
|
+
|
|
90
|
+
```ruby
|
|
91
|
+
GraphQuery::Age.available? # => false on Heroku Postgres
|
|
92
|
+
GraphQuery::Age.cypher('my_graph', 'MATCH (a)-[:KNOWS]->(b) RETURN a, b', columns: %w[a b])
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
It's a pass-through for databases that have it, not a second engine: everything else in graph_query runs on the CTE
|
|
96
|
+
walker, which is also why `GraphQuery.cypher` works on Heroku Postgres, RDS and anywhere else without AGE.
|
|
97
|
+
|
|
98
|
+
## Tests
|
|
99
|
+
|
|
100
|
+
The behaviour is written as shared examples (`spec/support/graph_query_examples.rb`) over a small graph in `gq_`
|
|
101
|
+
tables, so an app can run the same examples against its own database. On their own:
|
|
102
|
+
|
|
103
|
+
```sh
|
|
104
|
+
createdb graph_query_test
|
|
105
|
+
GRAPH_QUERY_DATABASE_URL=postgres:///graph_query_test bundle exec rake
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`rake` runs the specs, RuboCop and `rbs validate`.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Reference
|
|
2
|
+
|
|
3
|
+
## On every model
|
|
4
|
+
|
|
5
|
+
| Method | |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `graph_edge(name, association:)` | an edge from an association |
|
|
8
|
+
| `graph_edge(name, to:, through:, source:, target:)` | an edge from a join model's columns |
|
|
9
|
+
| `graph_edge(name, to:, sql:)` | an edge from SQL selecting `source_id`, `target_id` |
|
|
10
|
+
| `graph_edge(name, to:, computed: -> { ... })`, `graph_edge(name, to:) { ... }` | an edge from a relation or SQL built per query |
|
|
11
|
+
| ... `where:` | a Hash or scope Proc the edge's rows must match |
|
|
12
|
+
| `Model.traverse(names = nil, **options)` | a Query from the current scope |
|
|
13
|
+
| `Model.graph` | a Query from the current scope, no steps yet |
|
|
14
|
+
| `Model.graph_match(pattern, params: {}, **bindings)` | a Match whose first node is the current scope |
|
|
15
|
+
| `record.traverse(...)`, `record.graph` | the same from one record |
|
|
16
|
+
| `graph_mutation(name = nil, arguments: {}, returns: nil, description: nil)` | mark a method as a [graph mutation](#writes) |
|
|
17
|
+
| `Model.graph_mutations` | the model's graph mutations, by name |
|
|
18
|
+
|
|
19
|
+
`to:`, `through:` and `via:` take a model class or its name.
|
|
20
|
+
|
|
21
|
+
## GraphQuery
|
|
22
|
+
|
|
23
|
+
| Method | |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `GraphQuery.from(scope)` | a Query from a relation, record or model |
|
|
26
|
+
| `GraphQuery.from_pairs(pairs)` | a Query from `[[type, id], ...]` of any models |
|
|
27
|
+
| `GraphQuery.from_query(query)` | a Query from the nodes another one reaches |
|
|
28
|
+
| `GraphQuery.match(pattern, params: {}, **bindings)` | a Match |
|
|
29
|
+
| `GraphQuery.cypher(query, **params)` | a relation, pluck rows or a count (see [Cypher queries](#cypher)) |
|
|
30
|
+
| `GraphQuery.transaction { \|graph\| ... }` | a [Transaction](#writes) in one database transaction |
|
|
31
|
+
| `GraphQuery.max_depth`, `max_depth=` | the hop cap for counted unbounded steps (32) |
|
|
32
|
+
| `GraphQuery.registry.all` | every declared edge |
|
|
33
|
+
|
|
34
|
+
## GraphQuery::Query
|
|
35
|
+
|
|
36
|
+
| Method | |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `traverse(names = nil, depth: 1, direction: :out, to: nil, where: nil, through: nil, edge_where: nil)` | add a step |
|
|
39
|
+
| `out(names, **)`, `inbound(names, **)`, `both(names, **)` | a step with the direction fixed |
|
|
40
|
+
| `types` | model names the walk can end on |
|
|
41
|
+
| `to_relation(model = nil)`, `nodes` | reached nodes as a relation |
|
|
42
|
+
| `with_depth(model = nil)` | that relation with `graph_depth` |
|
|
43
|
+
| `pairs`, `records` | every reached node, any model |
|
|
44
|
+
| `by_origin(model = nil)`, `origin_pairs(model = nil)` | reached nodes grouped by start node |
|
|
45
|
+
| `polymorphic(scope, name)` | rows of scope whose polymorphic `name` points at a reached node |
|
|
46
|
+
| `paths` | every simple path |
|
|
47
|
+
| `to_sql(origin: false, depth: false, path: false)` | the statement |
|
|
48
|
+
| relation methods | delegated to `to_relation` when the walk reaches one model |
|
|
49
|
+
|
|
50
|
+
## GraphQuery::Match
|
|
51
|
+
|
|
52
|
+
| Method | |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| `nodes(var = nil, model: nil)` | a node variable's matches (default: the last node) |
|
|
55
|
+
| `paths` | every full match's path |
|
|
56
|
+
| `query(upto = all)` | the Query for the pattern (up to a node index) |
|
|
57
|
+
| relation methods | delegated to `nodes` |
|
|
58
|
+
|
|
59
|
+
## GraphQuery::Cypher
|
|
60
|
+
|
|
61
|
+
| Method | |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| `Cypher.new(query, params = {})` | parse a query (raises on bad syntax) |
|
|
64
|
+
| `result` | what `GraphQuery.cypher` returns |
|
|
65
|
+
| `nodes(:var)` | any node variable's matches, as a relation |
|
|
66
|
+
| `patterns`, `items`, `orders`, `skip`, `limit`, `distinct` | the parsed query |
|
|
67
|
+
|
|
68
|
+
## GraphQuery::Transaction
|
|
69
|
+
|
|
70
|
+
| Method | |
|
|
71
|
+
| --- | --- |
|
|
72
|
+
| `link(from, name, to, via: nil, attributes: {})` | add an edge (the written record, or nil if it was already there) |
|
|
73
|
+
| `unlink(from, name, to, via: nil)` | remove an edge |
|
|
74
|
+
| `relink(new_from, name, to, from:, via: nil, attributes: {})` | move an edge to a new source |
|
|
75
|
+
| `linked?(from, name, to, via: nil)` | whether an edge is there |
|
|
76
|
+
| `create`, `update`, `destroy` | write nodes |
|
|
77
|
+
| `changes` | every write, in order |
|
|
78
|
+
|
|
79
|
+
## GraphQuery::GraphQL
|
|
80
|
+
|
|
81
|
+
Loaded with `require 'graph_query/graphql'`.
|
|
82
|
+
|
|
83
|
+
| Method | |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| `Fields#graph_field(name, type, edge: \| pattern: \| &block, scope:, model:, depth:, ...)` | a field backed by a walk, batched |
|
|
86
|
+
| `Fields#graph_edges(model, only:, except:, scope:, type_for:)` | a field per declared edge |
|
|
87
|
+
| `MutationFields#graph_mutations(*models, only:, except:, base:)` | a mutation field per graph mutation |
|
|
88
|
+
| `TransactionalMutation` | include in a mutation: `resolve` runs in a transaction with `graph` |
|
|
89
|
+
| `GraphQuery::GraphQL.edge_mutation(from_model, name, to_model, action: :link, via:, graphql_name:, base:)` | a mutation that links or unlinks one edge by ID |
|
|
90
|
+
| `GraphQuery::GraphQL.type_for`, `type_for=` | model name to GraphQL type (default `"Types::<Model>Type"`) |
|
|
91
|
+
| `GraphQuery::GraphQL.record_for`, `record_for=` | `(model, id, context)` to a record |
|
|
92
|
+
|
|
93
|
+
## Errors
|
|
94
|
+
|
|
95
|
+
All inherit from `GraphQuery::Error`.
|
|
96
|
+
|
|
97
|
+
| Error | When |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| `GraphQuery::NoEdges` | a step names edges that don't leave its nodes, or can never reach its `to:` |
|
|
100
|
+
| `GraphQuery::AmbiguousResult` | a relation was asked of a walk that reaches several models |
|
|
101
|
+
| `GraphQuery::PatternError` | a pattern or query can't be read, binds an unknown variable, misses a `$param`, or has an unbound, unlabelled first node |
|
|
102
|
+
| `GraphQuery::UnsupportedCypher` | Cypher that reads fine but asks for what graph_query doesn't do (two variables in one condition, `RETURN a, b`, `OPTIONAL MATCH`) |
|
|
103
|
+
|
|
104
|
+
## Types
|
|
105
|
+
|
|
106
|
+
The gem ships signatures for both type checkers:
|
|
107
|
+
|
|
108
|
+
- **RBS** in `sig/graph_query.rbs`. Steep and other RBS tools find it in the installed gem; Active Record's own types
|
|
109
|
+
come from [gem_rbs_collection](https://github.com/ruby/gem_rbs_collection) (`rbs collection install`).
|
|
110
|
+
- **Sorbet** in `rbi/graph_query.rbi`. `bin/tapioca gem graph_query` copies it into `sorbet/rbi/gems`.
|
|
111
|
+
|
|
112
|
+
Both describe `graph_edge`, `graph_mutation`, `traverse`, `graph` and `graph_match` on every model, and `Query`,
|
|
113
|
+
`Match`, `Cypher`, `Pattern`, `Edge`, `Transaction`, `Mutation` and the errors. The GraphQL module isn't typed:
|
|
114
|
+
graphql-ruby's class DSL has no signatures to build on.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module GraphQuery
|
|
4
|
+
# Apache AGE, when the database has it: real Cypher over a graph AGE stores itself. Heroku Postgres (and most
|
|
5
|
+
# hosted Postgres) doesn't offer AGE, so Query's recursive CTEs over your own tables are the default and need
|
|
6
|
+
# nothing installed; this is a pass-through for databases that do have it.
|
|
7
|
+
module Age
|
|
8
|
+
module_function
|
|
9
|
+
|
|
10
|
+
def available?(connection = ActiveRecord::Base.connection)
|
|
11
|
+
connection.select_value("SELECT 1 FROM pg_extension WHERE extname = 'age'").present?
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
# Runs a Cypher query in an AGE graph and returns its rows (agtype values as text), one column per name in
|
|
15
|
+
# columns.
|
|
16
|
+
def cypher(graph, query, columns: [:result], connection: ActiveRecord::Base.connection)
|
|
17
|
+
raise Error, 'Apache AGE is not installed in this database' unless available?(connection)
|
|
18
|
+
|
|
19
|
+
tag = '$graph_query$'
|
|
20
|
+
raise ArgumentError, "the query can't contain #{tag}" if query.include?(tag)
|
|
21
|
+
|
|
22
|
+
list = columns.map { "#{connection.quote_column_name(it)} agtype" }.join(', ')
|
|
23
|
+
connection.transaction(requires_new: true) do
|
|
24
|
+
connection.execute("LOAD 'age'")
|
|
25
|
+
connection.execute('SET LOCAL search_path = ag_catalog, "$user", public')
|
|
26
|
+
name = connection.quote(graph.to_s)
|
|
27
|
+
connection.select_rows("SELECT * FROM cypher(#{name}, #{tag}#{query}#{tag}) AS (#{list})")
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
end
|
|
31
|
+
end
|