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.
@@ -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.
@@ -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