rails_age 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45fb3b7f94084761a6a3d6a26c9e4d86f3b790768ba52d5a5735713bb978d37b
-  data.tar.gz: af3866f393670857680d9334280058a0542155f3b76cb2cc64648fa0875e9f92
+  metadata.gz: 349925c4b715d64987c69a6a20b23e67c9076d91152477a976ade763805fdbf7
+  data.tar.gz: 4c7f1e430fe94ac3cb59eac8e6cb94bc03edab9532074c0df75be233b1210973
 SHA512:
-  metadata.gz: 774867c2584780ca6bbae3edbdf82fd592ebb3b3cb65c8f97400ceba5b37db650ce7c0ec9da1b45b30c2cf789e1d2e2ca776b97cbfc8ac431b3af234b4ba9efe
-  data.tar.gz: 05c03b0e12a5c77a53463cdfae58cce43b1f0cddfb811cad4a81e9ff137d49930434f53cbe0f6858e933eca15e9ce7e98b4d7cf57cb24d690a3a0d2b58cfc314
+  metadata.gz: af26f1a10253235703203804e508aa0d0dfbe7e44cc92097f70111587663c9af75e6cfd730fcb0986dc6093bb9bb16c847ab66ad7d3249057d3fe8adf443c78e
+  data.tar.gz: f98980a1937efeef70c1e548b2f62f5b2a7e2f383f707a92e8392a8f45b1bc9ac882a1f478fff0f24f1fcb3cb145e0f037202356ea4a2e76737ee81f4c70b459

data/CHANGELOG.md

@@ -1,10 +1,37 @@
 # Change Log
 
+## VERSION 0.3.0 - 2024-xx-xx
+
+- **cypher**
+  * query support
+  * paths support
+  * select attributes support
+- **Paths**
+  * ?
+
+## VERSION 0.2.0 - 2024-05-26
+
+- **Edges**
+  * add class methods to find_edge(with {properties, end_id, start_id})
+  * add missing methods to use in rails controllers
+  * validate edge start- & end-nodes are valid
+  * add unique edge validations
+- **Nodes**
+  * add missing methods to use in rails controllers
+  * add unique node validations
+
 ## VERSION 0.1.0 - 2024-05-21
 
 Initial release has the following features:
 
-- Nodes
-- Edges
-  That can be used within Rails applications using a Rails API.
-  See the [README](README.md) for more information.
+- **Nodes:**
+  * Create, Read, Update, Delete & .find(by id), .find_by(age_property), .all
+  * verified with usage in a controller and views
+- **Edges:**
+  * Create, Read, Update, Delete & .find(by id), .find_by(age_property), .all
+  * verified with usage in a controller and views
+- **Entities:**
+  * find (by id), find_by(age_property), all; when class/label and/or edge/node is unknown)
+
+These can be used within Rails applications using a Rails APIs including within controllers and views.
+See the [README](README.md) for more information.

data/README.md

@@ -4,6 +4,8 @@ Simplify Apache Age usage within a Rails application.
 
 ## Installation
 
+**NOTE:** you must be using Postgres as your database! Apache Age requires it.
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -22,6 +24,74 @@ Or install it yourself as:
 $ gem install rails_age
 ```
 
+finally (tempoarily you need to copy and run the migration)
+https://github.com/marpori/rails_age/blob/main/db/migrate/20240521062349_configure_apache_age.rb
+
+```bash
+# db/migrate/20240521062349_configure_apache_age.rb
+class ConfigureApacheAge < ActiveRecord::Migration[7.1]
+  def up
+    # Allow age extension
+    execute('CREATE EXTENSION IF NOT EXISTS age;')
+
+    # Load the age code
+    execute("LOAD 'age';")
+
+    # Load the ag_catalog into the search path
+    execute('SET search_path = ag_catalog, "$user", public;')
+
+    # Create age_schema graph if it doesn't exist
+    execute("SELECT create_graph('age_schema');")
+  end
+
+  def down
+    execute <<-SQL
+      DO $$
+      BEGIN
+        IF EXISTS (
+          SELECT 1
+          FROM pg_constraint
+          WHERE conname = 'fk_graph_oid'
+        ) THEN
+          ALTER TABLE ag_catalog.ag_label
+          DROP CONSTRAINT fk_graph_oid;
+        END IF;
+      END $$;
+    SQL
+
+    execute("SELECT drop_graph('age_schema', true);")
+    execute('DROP SCHEMA IF EXISTS ag_catalog CASCADE;')
+    execute('DROP EXTENSION IF EXISTS age;')
+  end
+end
+```
+
+and fix the TOP of `schema.rb` file to match the following (note: the version number should be the same as the LARGEST version number in your `db/migrations` folder)
+https://github.com/marpori/rails_age/blob/main/db/schema.rb
+
+```ruby
+# db/schema.rb
+ActiveRecord::Schema[7.1].define(version: 2024_05_21_062349) do
+  # These are extensions that must be enabled in order to support this database
+  enable_extension "plpgsql"
+
+  # Allow age extension
+  execute('CREATE EXTENSION IF NOT EXISTS age;')
+
+  # Load the age code
+  execute("LOAD 'age';")
+
+  # Load the ag_catalog into the search path
+  execute('SET search_path = ag_catalog, "$user", public;')
+
+  # Create age_schema graph if it doesn't exist
+  execute("SELECT create_graph('age_schema');")
+
+  # other migrations
+  # ...
+end
+```
+
 ## Contributing
 
 Create an MR and tests and I will review it.
@@ -34,7 +104,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 I suggest you creat a folder within app called `graphs` and under that create a folder called `nodes` and `edges`. This will help you keep your code organized.
 
-A full sample app can be found [here](https://github.com/btihen-dev/rails_graphdb_age_app) the summary usage is described below.
+A full sample app can be found [here](https://github.com/marpori/rails_age_demo_app) the summary usage is described below.
 
 ### Nodes
 
@@ -42,7 +112,7 @@ A full sample app can be found [here](https://github.com/btihen-dev/rails_graphd
 # app/graphs/nodes/company.rb
 module Nodes
   class Company
-    include ApacheAge::Vertex
+    include ApacheAge::Entities::Vertex
 
     attribute :company_name, :string
     validates :company_name, presence: true
@@ -54,7 +124,7 @@ end
 # app/graphs/nodes/person.rb
 module Nodes
   class Person
-    include ApacheAge::Vertex
+    include ApacheAge::Entities::Vertex
 
     attribute :first_name, :string, default: nil
     attribute :last_name, :string, default: nil
@@ -80,10 +150,12 @@ end
 ```ruby
 # app/graphs/edges/works_at.rb
 module Edges
-  class WorksAt
-    include ApacheAge::Edge
+  class HasJob
+    include ApacheAge::Entities::Edge
 
     attribute :employee_role, :string
+    attribute :start_node, :person # if using optional age types
+    # attribute :end_node, :person # if using optional age types
     validates :employee_role, presence: true
   end
 end
@@ -98,10 +170,46 @@ fred.to_h
 quarry = Nodes::Company.create(company_name: 'Bedrock Quarry')
 quarry.to_h
 
-job = Edges::WorksAt.create(start_node: fred, end_node: quarry, employee_role: 'Crane Operator')
+job = Edges::HasJob.create(start_node: fred, end_node: quarry, employee_role: 'Crane Operator')
 job.to_h
 ```
 
+### Update Routes
+
+```ruby
+Rails.application.routes.draw do
+  # mount is not needed with the engine
+  # mount RailsAge::Engine => "/rails_age"
+
+  # defines the route for the people controller
+  resources :people
+
+  # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
+  # Can be used by load balancers and uptime monitors to verify that the app is live.
+  get 'up' => 'rails/health#show', as: :rails_health_check
+
+  # Defines the root path route ("/")
+  root 'people#index'
+end
+```
+
+### Types (Optional)
+
+```ruby
+# spec/dummy/config/initializers/types.rb
+require 'apache_age/types/age_type_generator'
+
+Rails.application.config.to_prepare do
+  # Ensure the files are loaded
+  require_dependency 'nodes/company'
+  require_dependency 'nodes/person'
+
+  # Register the custom types
+  ActiveModel::Type.register(:company, ApacheAge::Types::AgeTypeGenerator.create_type_for(Nodes::Company))
+  ActiveModel::Type.register(:person, ApacheAge::Types::AgeTypeGenerator.create_type_for(Nodes::Person))
+end
+```
+
 ### Controller Usage
 
 ```ruby
@@ -176,3 +284,9 @@ class PeopleController < ApplicationController
   end
 end
 ```
+
+### Views
+
+```erb
+
+```

data/lib/apache_age/entities/class_methods.rb

@@ -0,0 +1,112 @@
+module ApacheAge
+  module Entities
+    module ClassMethods
+      # for now we only allow one predertimed graph
+      def create(attributes)
+        instance = new(**attributes)
+        instance.save
+        instance
+      end
+
+      def find_edge(attributes)
+        where_attribs =
+          attributes
+          .compact
+          .except(:end_id, :start_id, :end_node, :start_node)
+          .map { |k, v| "find.#{k} = '#{v}'" }.join(' AND ')
+        where_attribs = where_attribs.empty? ? nil : where_attribs
+
+        end_id = attributes[:end_id] || attributes[:end_node]&.id
+        start_id = attributes[:start_id] || attributes[:start_node]&.id
+        where_end_id = end_id ? "id(end_node) = #{end_id}" : nil
+        where_start_id = start_id ? "id(start_node) = #{start_id}" : nil
+
+        where_clause = [where_attribs, where_start_id, where_end_id].compact.join(' AND ')
+        return nil if where_clause.empty?
+
+        cypher_sql = find_edge_sql(where_clause)
+        execute_find(cypher_sql)
+      end
+
+      def find_by(attributes)
+        where_clause = attributes.map { |k, v| "find.#{k} = '#{v}'" }.join(' AND ')
+        cypher_sql = find_sql(where_clause)
+        execute_find(cypher_sql)
+      end
+
+      def find(id)
+        where_clause = "id(find) = #{id}"
+        cypher_sql = find_sql(where_clause)
+        execute_find(cypher_sql)
+      end
+
+      def all
+        age_results = ActiveRecord::Base.connection.execute(all_sql)
+        return [] if age_results.values.count.zero?
+
+        age_results.values.map do |result|
+          json_string = result.first.split('::').first
+          hash = JSON.parse(json_string)
+          attribs = hash.except('label', 'properties').merge(hash['properties']).symbolize_keys
+
+          new(**attribs)
+        end
+      end
+
+      # Private stuff
+
+      def age_graph = 'age_schema'
+      def age_label = name.gsub('::', '__')
+      def age_type = name.constantize.new.age_type
+
+      def match_clause
+        age_type == 'vertex' ? "(find:#{age_label})" : "(start_node)-[find:#{age_label}]->(end_node)"
+      end
+
+      def execute_find(cypher_sql)
+        age_result = ActiveRecord::Base.connection.execute(cypher_sql)
+        return nil if age_result.values.count.zero?
+
+        age_type = age_result.values.first.first.split('::').last
+        json_data = age_result.values.first.first.split('::').first
+
+        hash = JSON.parse(json_data)
+        attribs = hash.except('label', 'properties').merge(hash['properties']).symbolize_keys
+
+        new(**attribs)
+      end
+
+      def all_sql
+        <<-SQL
+        SELECT *
+        FROM cypher('#{age_graph}', $$
+            MATCH #{match_clause}
+            RETURN find
+        $$) as (#{age_label} agtype);
+        SQL
+      end
+
+      def find_sql(where_clause)
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH #{match_clause}
+              WHERE #{where_clause}
+              RETURN find
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+
+      def find_edge_sql(where_clause)
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH #{match_clause}
+              WHERE #{where_clause}
+              RETURN find
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+    end
+  end
+end

data/lib/apache_age/entities/common_methods.rb

@@ -0,0 +1,118 @@
+module ApacheAge
+  module Entities
+    module CommonMethods
+      # for now we just can just use one schema
+      def age_graph = 'age_schema'
+      def age_label = self.class.name.gsub('::', '__')
+      def persisted? = id.present?
+      def to_s = ":#{age_label} #{properties_to_s}"
+
+      def to_h
+        base_h = attributes.to_hash
+        if age_type == 'edge'
+          # remove the nodes (in attribute form and re-add in hash form)
+          base_h = base_h.except('start_node', 'end_node')
+          base_h[:end_node] = end_node.to_h if end_node
+          base_h[:start_node] = start_node.to_h if start_node
+        end
+        base_h.symbolize_keys
+      end
+
+      def update_attributes(attribs)
+        attribs.except(id:).each do |key, value|
+          send("#{key}=", value) if respond_to?("#{key}=")
+        end
+      end
+
+      def update(attribs)
+        update_attributes(attribs)
+        save
+      end
+
+      def save
+        return false unless valid?
+
+        cypher_sql = (persisted? ? update_sql : create_sql)
+        response_hash = execute_sql(cypher_sql)
+
+        self.id = response_hash['id']
+
+        if age_type == 'edge'
+          self.end_id = response_hash['end_id']
+          self.start_id = response_hash['start_id']
+          # reload the nodes? (can we change the nodes?)
+          # self.end_node = ApacheAge::Entity.find(end_id)
+          # self.start_node = ApacheAge::Entity.find(start_id)
+        end
+
+        self
+      end
+
+      def destroy
+        match_clause = (age_type == 'vertex' ? "(done:#{age_label})" : "()-[done:#{age_label}]->()")
+        delete_clause = (age_type == 'vertex' ? 'DETACH DELETE done' : 'DELETE done')
+        cypher_sql =
+          <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH #{match_clause}
+              WHERE id(done) = #{id}
+   	          #{delete_clause}
+              return done
+          $$) as (deleted agtype);
+          SQL
+
+        hash = execute_sql(cypher_sql)
+        return nil if hash.blank?
+
+        self.id = nil
+        self
+      end
+      alias destroy! destroy
+      alias delete destroy
+
+      # private
+
+      def age_properties
+        attrs = attributes.except('id')
+        attrs = attrs.except('end_node', 'start_node', 'end_id', 'start_id') if age_type == 'edge'
+        attrs.symbolize_keys
+      end
+
+      def age_hash
+        hash =
+          {
+            id:,
+            label: age_label,
+            properties: age_properties
+          }
+        hash.merge!(end_id:, start_id:) if age_type == 'edge'
+        hash.transform_keys(&:to_s)
+      end
+
+      def properties_to_s
+        string_values =
+          age_properties.each_with_object([]) do |(key, val), array|
+            array << "#{key}: '#{val}'"
+          end
+        "{#{string_values.join(', ')}}"
+      end
+
+      def age_alias
+        return nil if id.blank?
+
+        # we start the alias with a since we can't start with a number
+        'a' + Digest::SHA256.hexdigest(id.to_s).to_i(16).to_s(36)[0..9]
+      end
+
+      def execute_sql(cypher_sql)
+        age_result = ActiveRecord::Base.connection.execute(cypher_sql)
+        age_type = age_result.values.first.first.split('::').last
+        json_data = age_result.values.first.first.split('::').first
+        # json_data = age_result.to_a.first.values.first.split("::#{age_type}").first
+
+        JSON.parse(json_data)
+      end
+    end
+  end
+end

data/lib/apache_age/entities/edge.rb

@@ -0,0 +1,98 @@
+module ApacheAge
+  module Entities
+    module Edge
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveModel::Model
+        include ActiveModel::Dirty
+        include ActiveModel::Attributes
+
+        attribute :id, :integer
+        attribute :end_id, :integer
+        attribute :start_id, :integer
+        # allow user to optionally specify the class type (or not) thus not adding: `:vertex`
+        attribute :end_node
+        attribute :start_node
+
+        validates :end_node, :start_node, presence: true
+        validate :validate_nodes
+
+        extend ApacheAge::Entities::ClassMethods
+        include ApacheAge::Entities::CommonMethods
+      end
+
+      def initialize(**attributes)
+        super
+        self.end_id ||= end_node.id if end_node
+        self.start_id ||= start_node.id if start_node
+        self.end_node ||= Entity.find(end_id) if end_id
+        self.start_node ||= Entity.find(start_id) if start_id
+      end
+
+      def age_type = 'edge'
+      def end_class = end_node.class
+      def start_class = start_node.class
+      def end_node_class = end_node.class
+      def start_node_class = start_node.class
+
+      # Private methods
+
+      # Custom validation method to validate start_node and end_node
+      def validate_nodes
+        errors.add(:start_node, 'invalid') if start_node && !start_node.valid?
+        errors.add(:end_node, 'invalid') if end_node && !end_node.valid?
+      end
+
+      # Discover attribute class
+      # name_type = model.class.attribute_types['name']
+      # age_type = model.class.attribute_types['age']
+      # company_type = model.class.attribute_types['company']
+      # # Determine the class from the attribute type (for custom types)
+      # name_class = name_type.class # This will generally be ActiveModel::Type::String
+      # age_class = age_type.class   # This will generally be ActiveModel::Type::Integer
+      # # For custom types, you may need to look deeper
+      # company_class = company_type.cast_type.class
+
+      # AgeSchema::Edges::HasJob.create(
+      #   start_node: fred, end_node: quarry, employee_role: 'Crane Operator'
+      # )
+      # SELECT *
+      # FROM cypher('age_schema', $$
+      #     MATCH (start_vertex:Person), (end_vertex:Company)
+      #     WHERE id(start_vertex) = 1125899906842634 and id(end_vertex) = 844424930131976
+      #     CREATE (start_vertex)-[edge:HasJob {employee_role: 'Crane Operator'}]->(end_vertex)
+      #     RETURN edge
+      # $$) as (edge agtype);
+      def create_sql
+        self.start_node = start_node.save unless start_node.persisted?
+        self.end_node = end_node.save unless end_node.persisted?
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH (from_node:#{start_node.age_label}), (to_node:#{end_node.age_label})
+              WHERE id(from_node) = #{start_node.id} and id(to_node) = #{end_node.id}
+              CREATE (from_node)-[edge#{self}]->(to_node)
+              RETURN edge
+          $$) as (edge agtype);
+        SQL
+      end
+
+      # So far just properties of string type with '' around them
+      def update_sql
+        alias_name = age_alias || age_label.downcase
+        set_caluse =
+          age_properties.map { |k, v| v ? "#{alias_name}.#{k} = '#{v}'" : "#{alias_name}.#{k} = NULL" }.join(', ')
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH ()-[#{alias_name}:#{age_label}]->()
+              WHERE id(#{alias_name}) = #{id}
+              SET #{set_caluse}
+              RETURN #{alias_name}
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+    end
+  end
+end

data/lib/apache_age/entities/entity.rb

@@ -0,0 +1,69 @@
+module ApacheAge
+  module Entities
+    class Entity
+      class << self
+        def find_by(attributes)
+          where_clause = attributes.map { |k, v| "find.#{k} = '#{v}'" }.join(' AND ')
+          handle_find(where_clause)
+        end
+
+        def find(id)
+          where_clause = "id(find) = #{id}"
+          handle_find(where_clause)
+        end
+
+        private
+
+        def age_graph = 'age_schema'
+
+        def handle_find(where_clause)
+          # try to find a vertex
+          match_node = '(find)'
+          cypher_sql = find_sql(match_node, where_clause)
+          age_response = execute_find(cypher_sql)
+
+          if age_response.nil?
+            # if not a vertex try to find an edge
+            match_edge = '()-[find]->()'
+            cypher_sql = find_sql(match_edge, where_clause)
+            age_response = execute_find(cypher_sql)
+            return nil if age_response.nil?
+          end
+
+          instantiate_result(age_response)
+        end
+
+        def execute_find(cypher_sql)
+          age_result = ActiveRecord::Base.connection.execute(cypher_sql)
+          return nil if age_result.values.first.nil?
+
+          age_result
+        end
+
+        def instantiate_result(age_response)
+          age_type = age_response.values.first.first.split('::').last
+          json_string = age_response.values.first.first.split('::').first
+          json_data = JSON.parse(json_string)
+
+          age_label = json_data['label']
+          attribs = json_data.except('label', 'properties')
+                            .merge(json_data['properties'])
+                            .symbolize_keys
+
+          "#{json_data['label'].gsub('__', '::')}".constantize.new(**attribs)
+        end
+
+        def find_sql(match_clause, where_clause)
+          <<-SQL
+            SELECT *
+            FROM cypher('#{age_graph}', $$
+                MATCH #{match_clause}
+                WHERE #{where_clause}
+                RETURN find
+            $$) as (found agtype);
+          SQL
+        end
+      end
+    end
+  end
+end

data/lib/apache_age/entities/vertex.rb

@@ -0,0 +1,53 @@
+module ApacheAge
+  module Entities
+    module Vertex
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveModel::Model
+        include ActiveModel::Dirty
+        include ActiveModel::Attributes
+
+        attribute :id, :integer
+
+        extend ApacheAge::Entities::ClassMethods
+        include ApacheAge::Entities::CommonMethods
+      end
+
+      def age_type = 'vertex'
+
+      # AgeSchema::Nodes::Company.create(company_name: 'Bedrock Quarry')
+      # SELECT *
+      # FROM cypher('age_schema', $$
+      #     CREATE (company:Company {company_name: 'Bedrock Quarry'})
+      # RETURN company
+      # $$) as (Company agtype);
+      def create_sql
+        alias_name = age_alias || age_label.downcase
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              CREATE (#{alias_name}#{self})
+          RETURN #{alias_name}
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+
+      # So far just properties of string type with '' around them
+      def update_sql
+        alias_name = age_alias || age_label.downcase
+        set_caluse =
+          age_properties.map { |k, v| v ? "#{alias_name}.#{k} = '#{v}'" : "#{alias_name}.#{k} = NULL" }.join(', ')
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH (#{alias_name}:#{age_label})
+              WHERE id(#{alias_name}) = #{id}
+              SET #{set_caluse}
+              RETURN #{alias_name}
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+    end
+  end
+end