rails_age 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45fb3b7f94084761a6a3d6a26c9e4d86f3b790768ba52d5a5735713bb978d37b
-  data.tar.gz: af3866f393670857680d9334280058a0542155f3b76cb2cc64648fa0875e9f92
+  metadata.gz: aa956147280cd1ef2125eb39f3dd7867eadafde15806d95b90dab30d1290b135
+  data.tar.gz: a5b3a61d2fcf3026f9503b1bb4a9c6e60c6317f92266501f2890c2a02af1a01d
 SHA512:
-  metadata.gz: 774867c2584780ca6bbae3edbdf82fd592ebb3b3cb65c8f97400ceba5b37db650ce7c0ec9da1b45b30c2cf789e1d2e2ca776b97cbfc8ac431b3af234b4ba9efe
-  data.tar.gz: 05c03b0e12a5c77a53463cdfae58cce43b1f0cddfb811cad4a81e9ff137d49930434f53cbe0f6858e933eca15e9ce7e98b4d7cf57cb24d690a3a0d2b58cfc314
+  metadata.gz: a2dbb2a72e8f64056bf6531fab29da715bdc89d1748dce2fe92a44de11b5a8c74dbc354c18a903472c996c90e01f7947c921819d3cded09b4ffbfe1cbd0da33c
+  data.tar.gz: d5265daf4c4a1928bdd8f7f08a1efd884f8c4ce5da38d56321f58f6f507905a24d7587d2f92bacfe5a4141e500f7f81060726a2723368b443d8892bf2e66a9b3

data/CHANGELOG.md

@@ -1,10 +1,57 @@
 # Change Log
 
+## VERSION 0.4.0 - 2024-xx-xx
+
+- **Edges**
+  * `find_edge` is deprecated - use `find_by` with :start_node, :end_node to find an edge with specific nodes
+- **cypher**
+  * query support
+  * paths support
+  * select attributes support
+- **Paths**
+  * ?
+
+## VERSION 0.3.1 - 2024-xx-xx
+
+- **Genetator**
+  * add `rails generate apache_age:node` to create a node model (with its type in initializer)
+  * add `rails generate apache_age:edge` to create an edge model (with its type in initializer)
+- **Installer**
+  * refactored into multiple independent tasks?
+
+## VERSION 0.3.0 - 2024-05-28
+
+- **Installer** (`rails generate apache_age:install`)
+  * copy Age PG Extenstion migration to `db/migrate`
+  * run the AGE PG Migration
+  * repair `db/schema.rb` (rails mangles schema after running pg extension)
+  * update `database.yml` with schema search paths
+
+NOTE: the `rails generate apache_age:install` can be run at any time to repair the schema (or other config) file if needed.
+
+## 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`, `.all`, `.find(by id)`, `.find_by(age_properties)`
+  * verified with usage in a controller and views
+- **Edges:**
+  *`.create`, `.read`, `.update`, `.delete`, `.all`, `.find(by id)`, `.find_by(age_properties)`
+  * verified with usage in a controller and views
+- **Entities:**
+  * `.all`, `.find(id)`, `.find_by(age_property)` use these when class, label, edge, node
+
+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,24 +4,127 @@ 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
 gem "rails_age"
 ```
 
-And then execute:
+### Quick Install
 
 ```bash
 $ bundle
+$ bin/rails apache_age:install
+$ git add .
+$ git commit -m "Add Apache Age to Rails"
 ```
 
-Or install it yourself as:
+NOTE: it is important to add the db/schema.rb to your git repository because `rails db:migrate` will inappropriately modify the schema file.  However, you can run `bin/rails apache_age:install` at any time to repair the schema file if needed.
+
+### Manual Install
+
+create a migration to add the Apache Age extension to your database
+```bash
+$ bin/rails g migration AddApacheAge
+```
+copy the contents of https://github.com/marpori/rails_age/blob/main/db/migrate/20240521062349_add_apache_age.rb
+```ruby
+class AddApacheAge < 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
+```
+into your new migration file
 
+then run the migration
 ```bash
-$ gem install rails_age
+$ bin/rails db:migrate
 ```
 
+Rails migrate will mangle the schema `db/schema.rb` file.  You need to remove the lines that look like:
+```ruby
+  create_schema "ag_catalog"
+  create_schema "age_schema"
+
+  # These are extensions that must be enabled in order to support this database
+  enable_extension "age"
+  enable_extension "plpgsql"
+
+  # Could not dump table "_ag_label_edge" because of following StandardError
+  #   Unknown type 'graphid' for column 'id'
+
+  # Could not dump table "_ag_label_vertex" because of following StandardError
+  #   Unknown type 'graphid' for column 'id'
+
+  # Could not dump table "ag_graph" because of following StandardError
+  #   Unknown type 'regnamespace' for column 'namespace'
+
+  # Could not dump table "ag_label" because of following StandardError
+  #   Unknown type 'regclass' for column 'relation'
+
+  add_foreign_key "ag_label", "ag_graph", column: "graph", primary_key: "graphid", name: "fk_graph_oid"
+
+  # other migrations
+  # ...
+```
+
+and replace them with the following lines:
+```ruby
+  # 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
+  # ...
+```
+
+NOTE: I like to add the schema.rb to git so that it is easy to revert the unwanted changes and keep the desired changes.
+ALSO note that running: `bin/rails apache_age:install` will check and non-destructively repair any config files at any time (however a git commit before hand as a backup is a good idea incase something goes wrong!)
+
 ## Contributing
 
 Create an MR and tests and I will review it.
@@ -34,7 +137,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,10 +145,15 @@ 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
+    validates_with(
+      ApacheAge::Validators::UniqueVertexValidator,
+      attributes: [:company_name]
+    )
   end
 end
 ```
@@ -54,7 +162,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
@@ -78,13 +186,30 @@ end
 ### Edges
 
 ```ruby
-# app/graphs/edges/works_at.rb
+# app/graphs/edges/has_job.rb
 module Edges
-  class WorksAt
-    include ApacheAge::Edge
+  class HasJob
+    include ApacheAge::Entities::Edge
 
     attribute :employee_role, :string
+    attribute :start_node, :person
+    attribute :end_node, :company
+
     validates :employee_role, presence: true
+    validate :validate_unique
+    # or with a one-liner
+    # validates_with(
+    #   ApacheAge::Validators::UniqueEdgeValidator,
+    #   attributes: %i[employee_role start_node end_node]
+    # )
+
+    private
+
+    def validate_unique
+      ApacheAge::Validators::UniqueEdgeValidator
+        .new(attributes: %i[employee_role start_node end_node])
+        .validate(self)
+    end
   end
 end
 ```
@@ -98,10 +223,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 +337,9 @@ class PeopleController < ApplicationController
   end
 end
 ```
+
+### Views
+
+```erb
+
+```

data/db/migrate/{20240521062349_configure_apache_age.rb → 20240521062349_add_apache_age.rb}

@@ -1,4 +1,4 @@
-class ConfigureApacheAge < ActiveRecord::Migration[7.1]
+class AddApacheAge < ActiveRecord::Migration[7.1]
   def up
     # Allow age extension
     execute('CREATE EXTENSION IF NOT EXISTS age;')

data/lib/apache_age/entities/class_methods.rb

@@ -0,0 +1,119 @@
+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_by(attributes)
+        return nil if attributes.reject{ |k,v| v.blank? }.empty?
+
+        edge_keys = [:start_id, :start_node, :end_id, :end_node]
+        return find_edge(attributes) if edge_keys.any? { |key| attributes.include?(key) }
+
+        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 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 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