dse-driver 1.0.1

data/lib/dse/graph/result.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # An individual result of running a graph query. It wraps the JSON result and provides
+    # access to it as a hash. It also supports casting the result into a known
+    # domain object type: {Vertex}, {Edge}, and {Path} currently.
+    #
+    # @see ResultSet
+    class Result
+      # @return hash representation of the JSON result of a graph query if it's a complex result. A simple value
+      #   otherwise
+      attr_reader :value
+
+      # @private
+      def initialize(result)
+        @value = result
+      end
+
+      # Coerce this result into a domain object if possible.
+      # @return [Vertex, Edge, Result] a new wrapped object, or self if we can't cast it
+      def cast
+        type = @value['type'] if @value.is_a?(Hash)
+        case type
+        when 'vertex'
+          as_vertex
+        when 'edge'
+          as_edge
+        else
+          self
+        end
+      end
+
+      # Coerce this result into a {Vertex} object.
+      # @return [Vertex] a vertex domain object
+      # @raise [ArgumentError] if the result data does not represent a vertex
+      def as_vertex
+        Cassandra::Util.assert_instance_of(::Hash, @value)
+        Dse::Graph::Vertex.new(@value['id'], @value['label'], @value.fetch('properties', {}))
+      end
+
+      # Coerce this result into an {Edge} object.
+      # @return [Edge] an edge domain object.
+      # @raise [ArgumentError] if the result data does not represent an edge.
+      def as_edge
+        Cassandra::Util.assert_instance_of(::Hash, @value)
+        Dse::Graph::Edge.new(@value['id'], @value['label'], @value.fetch('properties', {}),
+                             @value['inV'], @value['inVLabel'],
+                             @value['outV'], @value['outVLabel'])
+      end
+
+      # Coerce this result into a {Path} object.
+      # @return [Path] a path domain object.
+      def as_path
+        Cassandra::Util.assert_instance_of(::Hash, @value)
+        Dse::Graph::Path.new(@value['labels'], @value['objects'])
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Result) && \
+          @value == other.value
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= 31 * 17 + @value.hash
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::Result:0x#{object_id.to_s(16)} " \
+          "@value=#{@value.inspect}>"
+      end
+    end
+  end
+end

data/lib/dse/graph/result_set.rb

@@ -0,0 +1,77 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Collection of results of running a graph query. It wraps a {Cassandra::Result}. When iterating
+    # over results, individual results may be well-known domain objects or a generic {Result}.
+    #
+    # @see Vertex
+    # @see Edge
+    # @see Path
+    # @see Result
+    class ResultSet
+      include Enumerable
+      extend Forwardable
+
+      # @private -- just for ==/eql?
+      attr_reader :parsed_results
+
+      # @!method execution_info
+      #   Query execution information, such as number of retries and all tried hosts, etc.
+      #   @return [Cassandra::Execution::Info]
+      #
+      # @!method empty?
+      #   @return [Boolean] whether it has any result data
+      #
+      # @!method size
+      #   @return [Integer] number of results
+      #
+      def_delegators :@results, :execution_info, :empty?, :size
+      alias length size
+
+      # @private
+      def initialize(results)
+        @results = results
+        @parsed_results = results.map do |r|
+          Result.new(JSON.parse(r.fetch('gremlin', {})).fetch('result', {})).cast
+        end
+      end
+
+      # @yieldparam result [Vertex, Edge, Path, Result] result object for a particular result
+      # @return [Enumerator, self] returns Enumerator if no block given
+      def each(&block)
+        @parsed_results.each(&block)
+      end
+
+      # Allow array indexing into the result-set.
+      # @param ind [Integer] index into the collection of query results.
+      def [](ind)
+        @parsed_results[ind]
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(ResultSet) && \
+          @parsed_results == other.parsed_results
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= 31 * 17 + @parsed_results.hash
+      end
+
+      # @private
+      def inspect
+        "#<Dse::ResultSet:0x#{object_id.to_s(16)} []=#{@parsed_results.inspect}>"
+      end
+    end
+  end
+end

data/lib/dse/graph/statement.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Encapsulates a graph statement, parameters, options, and idempotency. This is primarily useful for
+    # re-issuing the same statement multiple times the same way.
+    class Statement
+      include Cassandra::Statement
+
+      # @return [String] graph statement string
+      attr_reader :statement
+      # @return [Hash<String, String>] parameters to the statement
+      attr_reader :parameters
+      # @return [Options] graph options
+      attr_reader :options
+      # @private
+      attr_reader :simple_statement
+
+      # @param statement [String] graph statement
+      # @param parameters [Hash<String, String>] (nil) parameters to the statement
+      # @param options [Hash, Options] (nil) graph options
+      # @param idempotent [Boolean] (false) whether or not the statement is idempotent
+      def initialize(statement, parameters = nil, options = nil, idempotent = false)
+        # Save off statement and idempotent; easy stuff.
+        @statement = statement.freeze
+        @idempotent = idempotent.freeze
+        @parameters = parameters.freeze
+
+        # Convert the parameters into a one-element array with JSON; that's what we need to
+        # send to DSE over the wire. But if we have no params, nil is fine.
+        unless parameters.nil?
+          ::Cassandra::Util.assert_instance_of(::Hash, parameters, 'Graph parameters must be a hash')
+          # Some of our parameters may be geo-type values. Convert them to their wkt representation.
+          tweaked_params = {}
+          parameters.each do |name, value|
+            value = value.wkt if value.respond_to?(:wkt)
+            tweaked_params[name] = value
+          end
+          parameters = [tweaked_params.to_json]
+        end
+
+        # Graph options may be tricky. A few cases:
+        # 1. options is nil; then @options should be nil.
+        # 2. options is a Hash with a graph_options key; then @options is the referenced Options object.
+        #    We must validate that the referenced object *is* an Options.
+        # 3. options is an Options object; then just assign to @options.
+
+        unless options.nil?
+          Cassandra::Util.assert_instance_of_one_of([Dse::Graph::Options, ::Hash], options)
+          @options = if options.is_a?(Options)
+                       options
+                     elsif !options[:graph_options].nil?
+                       Cassandra::Util.assert_instance_of(Dse::Graph::Options, options[:graph_options])
+                       options[:graph_options]
+                     else
+                       Dse::Graph::Options.new(options)
+                     end
+        end
+
+        @simple_statement = Cassandra::Statements::Simple.new(@statement,
+                                                              parameters,
+                                                              parameters.nil? ? nil : [Cassandra::Types.varchar],
+                                                              @idempotent)
+      end
+
+      # @private
+      def accept(client, options)
+        simple_statement.accept(client, options)
+      end
+
+      # @private
+      def eql?(other)
+        other.is_a?(Statement) && \
+          @statement == other.statement && \
+          @parameters == other.parameters && \
+          @options == other.options && \
+          @idempotent == other.idempotent?
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        @hash ||= begin
+          h = 17
+          h = 31 * h + @statement.hash
+          h = 31 * h + @parameters.hash
+          h = 31 * h + @options.hash
+          h = 31 * h + @idempotent.hash
+          h
+        end
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::Statement:0x#{object_id.to_s(16)} " \
+          "@statement=#{@statement.inspect}, " \
+          "@parameters=#{@parameters.inspect}, " \
+          "@options=#{@options.inspect}, " \
+          "@idempotent=#{@idempotent.inspect}>"
+      end
+
+      protected
+
+      # @private
+      def method_missing(method, *args, &block)
+        # Delegate unrecognized method calls to our embedded statement.
+        @simple_statement.send(method, *args, &block)
+      end
+    end
+  end
+end

data/lib/dse/graph/vertex.rb

@@ -0,0 +1,107 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Vertex represents a vertex in DSE graph. Vertices have sophisticated properties. A given property can have
+    # multiple values, and each value can have a collection of meta-properties. To access a property of a vertex, you'd
+    # reference the {#properties} hash, and then get the n'th value, which is a {VertexProperty}, and then get the
+    # actual value from there.
+    # @example To get the first value of the 'name' property:
+    #   v.properties['name'][0].value
+    # @example Use array/hash dereference shortcut
+    #   v['name'][0].value
+    # @example Get all of the values of the 'name' property
+    #   values = v['name'].map do |vertex_prop|
+    #     vertex_prop.value
+    #   end
+    # @example Use the 'values' method on the array to do the heavy-lifting for you.
+    #   values = v['name'].values
+    # @example VertexProperty exposes meta-properties for a value:
+    #   meta1 = v['name'][0].properties['meta1']
+    #   # Shortcut
+    #   meta1 = v['name'][0]['meta1']
+    class Vertex
+      include Cassandra::Util
+
+      # @return [Hash] id of this vertex.
+      attr_reader :id
+      # @return [String] label of this vertex.
+      attr_reader :label
+      # @return [Hash<String, Array<VertexProperty>>] properties of this vertex.
+      attr_reader :properties
+
+      # @private
+      def initialize(id, label, properties)
+        @id = id
+        @label = label
+
+        # Vertex properties are structured like this:
+        # { 'name' => [
+        #     { 'id' => {... }, 'value' => 'some_val', 'properties' => { 'key' => 'value' } },
+        #     { 'id' => {... }, 'value' => 'some_val2', 'properties' => { 'key2' => 'value2' } }
+        # ], 'age' => [........], .... }
+        #
+        # When storing in @properties, we convert it to use VertexProperty's:
+        # { 'name' => [
+        #     vertex_prop1,
+        #     vertex_prop2
+        # ], 'age' => [........], .... }
+        #
+        # With that structure, we'll support syntactic sugar that lets users get to properties and meta-properties
+        # more easily:
+        #
+        # v['name'][0].value  -- get the first value of the 'name' property.
+        # v['name'][0]['key'] -- get the value of the 'key' meta-property of the first name property.
+
+        @properties = {}
+        properties.each do |prop_name, values|
+          vertex_props = values.map do |v|
+            VertexProperty.new(v)
+          end
+
+          # Add a 'values' method to the array to get the values of each prop
+          # in one array.
+          def vertex_props.values
+            map(&:value)
+          end
+
+          @properties[prop_name] = vertex_props
+        end
+      end
+
+      # @private
+      def [](key)
+        @properties[key]
+      end
+
+      # @private
+      def eql?(other)
+        # id's are unique among graph objects, so we only need to compare id's to test for equality.
+        other.is_a?(Vertex) && \
+          @id == other.id
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        # id's are unique among graph objects, so we only need to hash on the id for safely adding to a hash/set.
+        @hash ||= 31 * 17 + @id.hash
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::Vertex:0x#{object_id.to_s(16)} " \
+          "@id=#{@id.inspect}, " \
+          "@label=#{@label.inspect}, " \
+          "@properties=#{@properties.inspect}>"
+      end
+    end
+  end
+end

data/lib/dse/graph/vertex_property.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+
+#--
+#      Copyright (C) 2016 DataStax Inc.
+#
+#      This software can be used solely with DataStax Enterprise. Please consult the license at
+#      http://www.datastax.com/terms/datastax-dse-driver-license-terms
+#++
+
+module Dse
+  module Graph
+    # Encapsulates a vertex-property complex value. The name of the property is stored in the owning
+    # {Vertex}. This object contains a simple property value and any meta-properties that go with it.
+    #
+    # VertexProperty's are created when creating a Vertex object out of a graph query result hash. Access
+    # to meta-properties is done via the {#properties} attribute, but there is also a short-cut using
+    # array/hash dereference syntax:
+    # @example
+    #   val = vp.properties['meta1']
+    #   # is the same as
+    #   val = vp['meta1']
+    class VertexProperty
+      # @return [Hash] id of this property
+      attr_reader :id
+      # @return [String] value of this property
+      attr_reader :value
+      # @return [Hash<String, String>] meta-properties of this property
+      attr_reader :properties
+
+      # @private
+      def initialize(vertex_property_hash)
+        # Vertex properties have three attributes: id, value, properties. Pull those out of the hash.
+        @id = vertex_property_hash['id']
+        @value = vertex_property_hash['value']
+        @properties = vertex_property_hash.fetch('properties', {})
+      end
+
+      # @private
+      def [](key)
+        @properties[key]
+      end
+
+      # @private
+      def eql?(other)
+        # id's are unique among graph objects, so we only need to compare id's to test for equality.
+        other.is_a?(VertexProperty) && \
+          @id == other.id
+      end
+      alias == eql?
+
+      # @private
+      def hash
+        # id's are unique among graph objects, so we only need to hash on the id for safely adding to a hash/set.
+        @hash ||= 31 * 17 + @id.hash
+      end
+
+      # @private
+      def inspect
+        "#<Dse::Graph::VertexProperty:0x#{object_id.to_s(16)} " \
+          "@id=#{@id.inspect}, " \
+          "@value=#{@value.inspect}, " \
+          "@properties=#{@properties.inspect}>"
+      end
+    end
+  end
+end