Initial commit

Author: jeffreylovitz

Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'redis', '~> 4'
+gem 'terminal-table', '~> 1', '>= 1.8'
+

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2018, Redis Labs
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,44 @@
+# redisgraph-rb
+
+`redisgraph-rb` is a Ruby gem client for the RedisGraph module. It relies on `redis-rb` for Redis connection management and provides support for graph QUERY, EXPLAIN, and DELETE commands.
+
+## Usage
+```
+require 'redisgraph'
+
+graphname = "sample"
+
+r = RedisGraph.new(graphname)
+
+cmd = """CREATE (:person {name: 'Jim', age: 29})-[:works]->(:employer {name: 'Dunder Mifflin'})"""
+response = r.query(cmd)
+response.stats
+ => {:labels_added=>2, :nodes_created=>2, :properties_set=>3, :relationships_created=>1, :internal_execution_time=>0.705541}
+
+cmd = """MATCH ()-[:works]->(e:employer) RETURN e"""
+
+response = r.query(cmd)
+
+response.print_resultset
++----------------+
+| e.name         |
++----------------+
+| Dunder Mifflin |
++----------------+
+
+r.delete
+ => "Graph removed, internal execution time: 0.416024 milliseconds"
+```
+
+## Specifying Redis options
+RedisGraph connects to an active Redis server, defaulting to `host: localhost, port: 6379`. To provide custom connection parameters, instantiate a RedisGraph object with a `redis_options` hash:
+
+`r = RedisGraph.new("graphname", redis_options= { host: "127.0.0.1", port: 26380 })`
+
+These parameters are described fully in the documentation for https://github.com/redis/redis-rb
+
+## Running tests
+A simple test suite is provided, and can be run with:
+`ruby test/test_suite.rb`
+These tests expect a Redis server with the Graph module loaded to be available at localhost:6379
+

lib/redisgraph.rb

@@ -0,0 +1,44 @@
+require 'redis'
+require 'terminal-table'
+
+require_relative 'redisgraph/errors.rb'
+require_relative 'redisgraph/query_result.rb'
+require_relative 'redisgraph/connection.rb'
+
+class RedisGraph
+  attr_accessor :connection
+  attr_accessor :graphname
+
+  # The RedisGraph constructor instantiates a Redis connection
+  # and validates that the graph module is loaded
+  def initialize(graph, redis_options = {})
+    @graphname = graph
+    connect_to_server(redis_options)
+  end
+
+  # Execute a command and return its parsed result
+  def query(command)
+    begin
+    resp = @connection.call("GRAPH.QUERY", @graphname, command)
+    rescue Redis::CommandError => e
+      raise QueryError, e
+    end
+
+    QueryResult.new(resp)
+  end
+
+  # Return the execution plan for a given command
+  def explain(command)
+    begin
+    resp = @connection.call("GRAPH.EXPLAIN", @graphname, command)
+    rescue Redis::CommandError => e
+      raise QueryError, e
+    end
+  end
+
+  # Delete the graph and all associated keys
+  def delete
+    resp = @connection.call("GRAPH.DELETE", @graphname)
+  end
+end
+

lib/redisgraph/connection.rb

@@ -0,0 +1,16 @@
+class RedisGraph
+  def connect_to_server(options)
+    @connection = Redis.new(options)
+    self.verify_module()
+  end
+
+  # Ensure that the connected Redis server supports modules
+  # and has loaded the RedisGraph module
+  def verify_module()
+    redis_version = @connection.info["redis_version"]
+    major_version = redis_version.split('.').first.to_i
+    raise ServerError, "Redis 4.0 or greater required for RedisGraph support." unless major_version >= 4
+    resp = @connection.call("MODULE", "LIST")
+    raise ServerError, "RedisGraph module not loaded." unless resp.first && resp.first.include?("graph")
+  end
+end

lib/redisgraph/errors.rb

@@ -0,0 +1,10 @@
+class RedisGraph
+  class RedisGraphError < RuntimeError
+  end
+
+  class ServerError < RedisGraphError
+  end
+
+  class QueryError < RedisGraphError
+  end
+end

lib/redisgraph/query_result.rb

@@ -0,0 +1,59 @@
+class QueryResult
+  attr_accessor :columns
+  attr_accessor :resultset
+  attr_accessor :stats
+
+  def print_resultset
+    pretty = Terminal::Table.new headings: columns do |t|
+      resultset.each { |record| t << record }
+    end
+    puts pretty
+  end
+
+  def parse_resultset(response)
+    # Any non-empty result set will have multiple rows (arrays)
+    return nil unless response[0].length > 1
+    # First row is return elements / properties
+    @columns = response[0].shift
+    # Subsequent rows are records
+    @resultset = response[0]
+  end
+
+  # Read metrics about internal query handling
+  def parse_stats(response)
+    return nil unless response[1]
+
+    stats = {}
+
+    response[1].each do |stat|
+      line = stat.split(': ')
+      val = line[1].split(' ')[0]
+
+      case line[0]
+      when /^Labels added/
+        stats[:labels_added] = val.to_i
+      when /^Nodes created/
+        stats[:nodes_created] = val.to_i
+      when /^Nodes deleted/
+        stats[:nodes_deleted] = val.to_i
+      when /^Relationships deleted/
+        stats[:relationships_deleted] = val.to_i
+      when /^Properties set/
+        stats[:properties_set] = val.to_i
+      when /^Relationships created/
+        stats[:relationships_created] = val.to_i
+      when /^Query internal execution time/
+        stats[:internal_execution_time] = val.to_f
+      end
+    end
+    stats
+  end
+
+  def initialize(response)
+    # The response for any query is expected to be a nested array.
+    # The only top-level values will be the result set and the statistics.
+    @resultset = parse_resultset(response)
+    @stats = parse_stats(response)
+  end
+end
+

lib/redisgraph/version.rb

@@ -0,0 +1,3 @@
+class RedisGraph
+  VERSION = '1.0.0'
+end

redisgraph.gemspec

@@ -0,0 +1,24 @@
+require "./lib/redisgraph/version"
+
+Gem::Specification.new do |s|
+  s.name = "redisgraph"
+
+  s.version = RedisGraph::VERSION
+
+  s.license = 'BSD-3-Clause'
+
+  s.homepage = 'https://github.com/redislabs/redisgraph-rb'
+
+  s.summary = 'A client for RedisGraph'
+
+  s.description = 'A client that extends redis-rb to provide explicit support for the RedisGraph module.'
+
+  s.authors = ['Redis Labs']
+
+  s.email = '[email protected]'
+
+  s.files = `git ls-files`.split("\n")
+
+  s.add_runtime_dependency('redis', '~> 4')
+  s.add_runtime_dependency('terminal-table', '~> 1', '>= 1.8')
+end

test/test_suite.rb

@@ -0,0 +1,89 @@
+require_relative '../lib/redisgraph.rb'
+require "test/unit"
+include Test::Unit::Assertions
+
+# Helper functions
+# TODO it would be nice to have something like DisposableRedis
+
+# Connect to a Redis server on localhost:6379
+def connect_test
+  begin
+  @r = RedisGraph.new("rubytest")
+  rescue Redis::BaseError => e
+    puts e
+    puts "RedisGraph tests require that a Redis server with the graph module loaded be running on localhost:6379"
+    exit 1
+  end
+end
+
+# Ensure that the graph "rubytest" does not exist
+def delete_graph
+  @r.delete
+end
+
+# Test functions - each validates one or more EXPLAIN and QUERY calls
+
+def validate_node_creation
+  query_str = """CREATE (t:node {name: 'src'})"""
+  x = @r.query(query_str)
+  plan = @r.explain(query_str)
+  assert(plan =~ /Create/)
+  assert(x.resultset.nil?)
+  assert(x.stats[:labels_added] == 1)
+  assert(x.stats[:nodes_created] == 1)
+  assert(x.stats[:properties_set] == 1)
+  puts "Create node - PASSED"
+end
+
+def validate_node_deletion
+  query_str = """MATCH (t:node) WHERE t.name = 'src' DELETE t"""
+  plan = @r.explain(query_str)
+  assert(plan =~ /Delete/)
+  x = @r.query(query_str)
+  assert(x.resultset.nil?)
+  assert(x.stats[:nodes_deleted] == 1)
+  query_str = """MATCH (t:node) WHERE t.name = 'src' RETURN t"""
+  assert(x.resultset.nil?)
+  puts "Delete node - PASSED"
+end
+
+def validate_edge_creation
+  query_str = """CREATE (p:node {name: 'src1'})-[:edge]->(:node {name: 'dest1'}), (:node {name: 'src2'})-[:edge]->(q:node_type_2 {name: 'dest2'})"""
+  plan = @r.explain(query_str)
+  assert(plan =~ /Create/)
+  x = @r.query(query_str)
+  assert(x.resultset.nil?)
+  assert(x.stats[:nodes_created] == 4)
+  assert(x.stats[:properties_set] == 4)
+  assert(x.stats[:relationships_created] == 2)
+  puts "Add edges - PASSED"
+end
+
+def validate_edge_traversal
+  query_str = """MATCH (a)-[:edge]->(b:node) RETURN a, b"""
+  plan = @r.explain(query_str)
+  assert(plan.include?("Traverse"))
+  x = @r.query(query_str)
+  assert(x.resultset)
+  assert(x.columns.length == 2)
+  assert(x.resultset.length == 1)
+  assert(x.resultset[0] == ["src1", "dest1"])
+  puts "Traverse edge - PASSED"
+end
+
+def test_suite
+  puts "Running RedisGraph tests..."
+  connect_test
+  delete_graph # Clear the graph
+
+  # Test basic functionalities
+  validate_node_creation
+  validate_node_deletion
+  validate_edge_creation
+  validate_edge_traversal
+
+  delete_graph # Clear the graph again
+  puts "RedisGraph tests passed!"
+end
+
+test_suite