Make Cypher query execution return a Result instance

[paracycle]

This addresses two review comments on the Cypher blog post in rails-at-scale#431:

• ArgumentError on a syntax error should be a more specific error
• render mixes execution and rendering; the API should be query.run(graph).render(:json)

Execution and rendering are separate

Rubydex::Query#render(graph, format) is gone. The new shape is:

query = Rubydex::Query.parse("MATCH (c:Class) RETURN c.name")
result = query.run(graph)

result.rows.each { |row| puts row["c.name"] }
puts result.render(:json)

Query#run returns a Rubydex::Query::Result. That object owns the executed result set, so render never runs the query again. It is Enumerable over its rows, and it answers columns, rows, each, size, length, empty?, and render.

Specific errors

Class	Raised by
Rubydex::QueryError	The base class. Rescue it to catch either failure.
Rubydex::QuerySyntaxError	Query.parse, on invalid Cypher.
Rubydex::QueryExecutionError	Query#run, when the query fails against the graph.

ArgumentError remains for true argument faults, such as an unknown output format.

The Rust FFI reports the failure kind through a new CQueryErrorKind, so the C extension raises the matching class.

Verification

• bundle exec rake test: 300 Ruby runs and the full Rust suite. 0 failures.
• cargo fmt --check and rubocop: clean. cargo clippy reports no new warnings.
• CLI smoke test: the table and JSON output are unchanged. A syntax error still fails before indexing. An execution error aborts with its message.
• Compaction stress: Rubydex::Query::Result marks graph_obj and rows movable and implements dcompact, so GC.verify_compaction_references followed by GC.compact keeps every reference valid.

Follow-up

The blog post in rails-at-scale#431 still describes the old API. It needs the two snippets updated once this merges.

[dersam]

Should this be two separate PRs (one for errors, one for render)?

[paracycle]

Should this be two separate PRs (one for errors, one for render)?

I could split, but it felt natural to add the new exceptions while making the API change.

[Morriar]

One concern with lazy materialization: rows converts node cells by looking them up in the current graph state. If the graph changes after query.run(graph) but before the first result.rows, the executed result can change shape. For example:

result = Rubydex::Query.parse("MATCH (c:Class {name: 'Dog'}) RETURN c").run(graph)
graph.index_source("zoo.rb", "class Cat; end\n", "ruby")
graph.resolve

result.render(:json) # still has the Dog node from the executed result set
result.rows          # [{ "c" => "Dog" }], no longer a Declaration handle

Can we materialize the row cells at execution time, or have the result set carry the node category/kind/id captured during execution, so Result is independent of later graph mutations? I'd add a regression test for run; mutate graph; rows too.

[paracycle]

I've gone the other direction and implemented proper lazy materialization here which also checks for node invalidation too. Is that enough to address your concern?

[Morriar]

Looks like Result#render and Result#rows disagree based on graph mutations after execution. Do we need to rebase on #992?

[paracycle]

On the contrary, #992 is based on this branch, since it need this refactor to operate.

[st0012]

Let's hide it in rbi too?

[paracycle]

How? This isn't making the method private, it is completely removing it. How can we remove methods in RBI files?

[st0012]

I thought we can hide it by making Result.new private? Hide as using Sorbet to prevent users from calling it.

[paracycle]

I am not sure that I like that as a solution, since it only makes it private and doesn't mean it can't be called from other contexts:

class Bar
  class << self
    private

    def new = super
  end
end

class Baz < Bar
  (Instance = new) rescue puts "Error"
  puts "No error when creating: #{Instance}" if defined?(Instance)
end

Bar.new rescue puts "Error"
Baz.new rescue puts "Error"

gives:

❯ ruby bar.rb
No error when creating: #<Baz:0x0000000121aec870>
Error
Error

On the other hand, undef_method :new completely removes it:

class Bar
  class << self
    undef_method :new
  end
end

class Baz < Bar
  (Instance = new) rescue puts "Error"
  puts "No error when creating: #{Instance}" if defined?(Instance)
end

Bar.new rescue puts "Error"
Baz.new rescue puts "Error"

gives:

❯ ruby bar.rb
Error
Error
Error