arcadedb 0.4 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1855060886e9837ef486e44f07155ae99cd242f76aceccb8a7bf4c2ab515eca0
-  data.tar.gz: d99f2a402eba561fcf851a3838b3bec7eee58f1a788ab9fc7e2ce1208c33611a
+  metadata.gz: f030932c1444832b3ea224120f71cc655837ca732717b896ed8587a8cefc0dd4
+  data.tar.gz: 96f05185b21af4820ebc667d796635e4b0c6c3ac42b59dc360212df7b287934e
 SHA512:
-  metadata.gz: 78936dfe0069d531c1bcfd6191f0269ed84a44cd8e0321a37ef9d569048ff8a20d38d0a221d0b0b93f3e64f39d61a758d2978545beec86d27baf5836c3cdbf4a
-  data.tar.gz: 6ff4e9242c74887935074ed60810b144a08ad2dad7a6d3374bc0216f74873abb6a1b6f66428a2ed6e7fa9f49dec3ee07ebbe5cc64488744829f76eb037db286c
+  metadata.gz: 92ab840638f4a8e0cf56a5138d870bbb282223b9cc0c4b8f5bab39184712ce6742862ea0683a73b917e0b5a94acbd1bccc12ec6a52863caeba9a28b2aacf3132
+  data.tar.gz: 6fd195fb51f62fbcea2945f0688626084f8991936b745d6c939bae35bce4912414a80376535a379c3ca1166c4b62ffb2089c041d3951d87fe78ab5dcb421eae0

data/CHANGELOG.md

@@ -15,5 +15,36 @@ All notable changes to this project will be documented in this file.
 ## 0.4.0 - 2023.10.28
 - completely remove pg-stuff
 - substitute typhoreous with  HTTPX
-- include dry::monards to process raw-data
+
+## 0.4.1 - 2023.10.31
+- redesign of transactions. 
+- Type.execute performs non idempotent queries  in a (nested) transaction
+- Type.transmit performs non idempotent queries 
+- Type.query performs idempotent queries 
+- Type.create returns a rid
+- Type.insert returns a type-object
+- Vertex.nodes supports conditions on edges
+- Vertex.in, Vertex.out Vertex.inE, Vertex.outE support depth as second parameter
+- IRuby-Support. Formatted output for Base-Objects
+
+## 0.5.0 - 2023-12-12
+- Arcade::Match simple match-statement generator
+- return to Arcade::QueryError messages instead of HTTPX::HTTPError
+- The ProjectRoot Const is used to read configuration files (Changed from Arcade::ProjectRoot)
+
+## 0.5.1 - 2024-1-16
+- Included Arcade::RevisionRecord and Arcade::Revision model classes
+- Both provide basic support for audit proofed bookings
+## 0.5.2 - 2025-02-11
+- Include method Object#descendants (part of active-support)
+- Separate Dry::Type definitions to /lib/types.rb
+- added Vertex#coe (count of edeges) as service method for to_human
+- updated Match#inE, #outE methods to facilitate queries on properties on edges
+##       - 2025-03-15
+- support of Match.new vertex: {a prefetched Arcade::Vertex} and match.node( vertex: ...) 
+##       - 2025-03-25
+- support of Vertex.match( where conditions [, as: :return_element] )
+- added Vertex#match to build  'MATCH type: {class} rid: {rid}'
+
+
 

data/Gemfile.lock

@@ -1,10 +1,9 @@
 PATH
   remote: .
   specs:
-    arcadedb (0.4)
+    arcadedb (0.4.1)
       dry-configurable
       dry-core
-      dry-monads
       dry-schema
       dry-struct
       httpx
@@ -12,9 +11,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
     awesome_print (1.9.2)
-    base64 (0.1.1)
     coderay (1.1.3)
     concurrent-ruby (1.2.2)
     diff-lcs (1.5.0)
@@ -30,10 +27,6 @@ GEM
       concurrent-ruby (~> 1.0)
       dry-core (~> 1.0, < 2)
       zeitwerk (~> 2.6)
-    dry-monads (1.6.0)
-      concurrent-ruby (~> 1.0)
-      dry-core (~> 1.0, < 2)
-      zeitwerk (~> 2.6)
     dry-schema (1.13.3)
       concurrent-ruby (~> 1.0)
       dry-configurable (~> 1.0, >= 1.0.1)
@@ -72,11 +65,9 @@ GEM
       guard-compat (~> 1.1)
       rspec (>= 2.99.0, < 4.0)
     http-2-next (1.0.1)
-    httpx (1.0.2)
+    httpx (1.1.0)
       http-2-next (>= 1.0.1)
     ice_nine (0.11.2)
-    json (2.6.3)
-    language_server-protocol (3.17.0.3)
     listen (3.8.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
@@ -86,10 +77,6 @@ GEM
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
-    parallel (1.23.0)
-    parser (3.2.2.4)
-      ast (~> 2.4.1)
-      racc
     pastel (0.8.0)
       tty-color (~> 0.5)
     pry (0.14.2)
@@ -97,16 +84,12 @@ GEM
       method_source (~> 1.0)
     psych (5.1.1.1)
       stringio
-    racc (1.7.1)
-    rainbow (3.1.1)
     rake (13.0.6)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     rdoc (6.5.0)
       psych (>= 4.0.0)
-    regexp_parser (2.8.2)
-    rexml (3.2.6)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -131,21 +114,6 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.1)
-    rubocop (1.57.1)
-      base64 (~> 0.1.1)
-      json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
-      parallel (~> 1.10)
-      parser (>= 3.2.2.4)
-      rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.28.1, < 2.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.29.0)
-      parser (>= 3.2.1.0)
-    ruby-progressbar (1.13.0)
     sdoc (2.6.1)
       rdoc (>= 5.0)
     shellany (0.0.1)
@@ -168,7 +136,6 @@ DEPENDENCIES
   guard
   guard-rspec
   pastel
-  pry
   rake (~> 13.0)
   rb-inotify
   rspec
@@ -177,7 +144,6 @@ DEPENDENCIES
   rspec-given
   rspec-its
   rspec-legacy_formatters
-  rubocop
   sdoc
   terminal-table
   zeitwerk

data/README.md

@@ -5,19 +5,26 @@ Ruby Interface to a [Arcade Database](https://arcadedb.com/).
 The program utilizes the HTTP-JSON API to direct database queries to an ArcadeDB server. 
 The server's response is then mapped to an ORM (Object-Relational Mapping) based on DRY::Struct. 
 Each database type is represented by a dedicated Model Class, where complex queries are encapsulated. 
-The program also includes a  Query-Preprocessor for constructing custom queries in ruby fashion.
+The program also includes a  Query-Preprocessor and Match-statment generator for constructing custom queries in ruby fashion.
 
-***ArcadeDB internally uses `Arcade` as primary namespace**** 
+***ArcadeDB internally uses `Arcade` as primary namespace*** 
 
 ## Prerequisites
 
 A running AracdeDB-Instance. [Quick-Start-Guide](https://docs.arcadedb.com/#Quick-Start-Docker).
 
-[ArcadeDB V 22.10.1](https://github.com/ArcadeData/arcadedb/releases/tag/22.10.1)ff is supported
+## New Project
 
-## Config
-
-Edit the file `arcade.yml`  and  provide suitable databases for test, development and production environment.
+```
+mkdir project && cd project
+bundle init
+bundle add arcadedb
+bundle add pastel  # for console output
+mkdir model
+mkdir bin
+```
+copy `https://github.com/topofocus/arcadedb/blob/main/bin/console` to the `bin` directory  
+copy `https://github.com/topofocus/arcadedb/blob/main/arcade.yml` to the project root and modify to your needs
 
 ## Console
 
@@ -25,8 +32,18 @@ To start an interactive console, a script is provided in the bin-directory.
 ```
 $ cd bin && ./console.rb  t   ( or "d" or "p" for Test, Development and Production environment)
 
-**Database definitions  (model-files) of the test-suite are included!**
+**in Test environment Database definitions  (model-files) of the test-suite are included!**
+```
+
+## Add to a project
+Just require it in your program:
+```ruby
+require "arcade"
 ```
+## Config
+
+Add a file `arcade.yml` at the root of your program or in the `config`-dir  and  provide suitable databases for test, development and production environment.
+
 
 ## Examples  & Specs
 
@@ -39,14 +56,13 @@ The `spec`-files in the rspec-test-suite-section are worth reading, too.
 The adapter uses a 3 layer concept. 
 
 Top-Layer : `Arcade::Base`-Model-Objects. 
-They operate similar to ActiveRecord Model Objects but are based on [Dry-Struct](https://dry-rb.org/gems/dry-struct/1.0/).
+Similar to ActiveRecord Model Objects but based on [Dry-Struct](https://dry-rb.org/gems/dry-struct/1.0/).
 
 ```ruby
 # Example model file  /model/demo/user.rb
 module Demo
-  class Person < Arcade::Vertex
+  class User < Arcade::Vertex
     attribute :name, Types::Nominal::String
-    timestamps true
     
     def grandparents
       db.query( "select in('is_family') from #{rid} ") &.allocate_model
@@ -58,14 +74,14 @@ __END__
   CREATE INDEX on demo_user( name ) UNIQUE
 ```
 
-Only the `name` attribute is declared. Timestamps (created & updated attributes) are included, too
+Only the `name` attribute is declared. 
 
-`Demo::User.create_type`  creates the type and executes the database-commands after __END__.   
+`Demo::User.create_type`  creates the type and executes provided database-commands after `__END__`.   
 
-Other properties are schemaless. 
+Other properties are schemaless. They are present in the database and are mapped to the `value`-attribute on the ruby side.  
 
 ```ruby
-Person.create name: "Hubert", age: 35
+Person.insert name: "Hubert", age: 35
 Person.update set: { age: 36 }, where: { name: 'Hubert' }
 persons = Person.where "age > 40"
 persons.first.update age: 37
@@ -75,9 +91,118 @@ Person.all
 Person.delete all: true || where: age: 56 , ...
 ```
 
+### Nodes and Traverse
+
+`ArcadeDB` wraps common queries of bidirectional connected vertices.
+
+Suppose
+```ruby 
+m = Person.insert name: 'Hubert', age: 25
+f = Person.insert name: 'Pauline', age: 28
+m.assign via: IsMarriedTo, vertex: f , divorced: false
+
+```
+This creates the simple graph 
+>  Hubert --- is_married_to --> Pauline 
+>                  |
+>                  -- divorced (attribute on the edge)
+
+This can be queried through
+
+```ruby
+hubert =  Person.find name: 'Hubert'
+pauline = hubert.nodes( :out, via: IsMarriedTo ).first
+# or simply
+pauline = hubert.out.first
+
+```
+Conditions may be set, too. 
+```ruby
+hubert.nodes( :out, via: IsMarriedTo, where: "age < 30" )
+```
+gets all wives of hubert, who are younger then 30 years.  
+or
+```ruby
+Person.nodes( :outE, via: IsMarriedTo, where: { divorced: false } )
+
+```
+gets all wives where the divorced-condition, which is set on the edge, is false. 
+
+### Query
+
 A **Query Preprocessor** is implemented. Its adapted from ActiveOrient. The [documentation](https://github.com/topofocus/active-orient/wiki/OrientQuery)
-is still valid,  however the class has changed to `Arcade::Query`. 
+is still valid, but the class has changed to `Arcade::Query`. 
+
+### Match
 
+A simple **Match Statement Generator** is provided for convenience. As the [declarative syntax](https://github.com/ArcadeData/arcadedb-docs/blob/main/src/main/asciidoc/sql/SQL-Match.adoc)  is very intuitive, a preprocessor should not be 
+necessary. However, with the help of some ruby magic, the creation of match-statements is simply an no-brainer.
+
+```ruby
+a =  Arcade::Match.new( type: Person, as: :persons)
+                  .out( IsMarriedTo )
+                  .node( where: 'age < 30')
+a.to_s
+=>  Match { type: person, as: persons }.out('is_married_to'){ where: ( age < 30) } RETURN persons
+
+a.execute.select_results  #  sends the statement to the database and returns Arcade Objects. 
+```
+
+To query properties on Edges, `inE`, and `outE` are present.
+```ruby
+a =  Arcade::Match.new( type: Person, as: :persons)   ->  Match { type: person, as: persons}
+a.outE via: IsMarriedTo, where: { year: 1990..2000 }  ->  .outE('is_married_to'){ where: year between 1990 and 2000}
+                                                      ->  .outV('is_maried_to')  ...
+
+a.outE via: [IsMarriedTo, IsMarriedIn], where: { year: 1990..2000 }, as: :bride 
+                                                      ->   .outV('is_married_in') ... 
+```
+
+Match statements can also refer to a vertex:
+```ruby 
+p = Person.find name: 'tux'
+c = Person.find name: 'hilde'
+a = Arcade::Match.new( vertex: p )                    -> Match { type: person, rid: 2:0 }
+                 .out( IsMarriedTo )                  ->       .out('is_married_to')
+                 .node( as: :wife )                   ->       { as: wife }
+                 .out( HasChild )                     ->       .out('has_child')
+                 .node( vertex: c )                   ->       { type: person, rid: 2:1 }
+                                                      -> Return wife
+``` 
+fetches the vertex between two known vertices. This is the fastest lookup mechanism if the vertices are prefetched. 
+
+Arcade::Match-objects can be used as `from:` argument to Arcade::Query-Statements; hybrid queries are 
+easily constructed without extensive string-manipulations.
+
+#### Vertex based Match statements
+
+A `match`-method is implemented for  Vertex-Classes and vertices.
+
+The class-method takes any argument (except `as:`) as part of a `where`-condition.
+
+```ruby
+  
+m = Watchlist.match( symbol: 'iBit', as: :ibit ) 
+             .out( HasUnderlying)
+             .node( as: :u )
+           
+m.to_s
+  => "MATCH { type: watchlist, where: ( symbol='iBit' ), as: ibit }
+            .out('has_underlying'){ as: u } 
+      RETURN ibit,u "
+```
+
+The instance-method is extremly handy in web-applications. If the `rid` is part of the `params`-hash,
+associated nodes are easily selected
+
+```ruby
+params[:rid] =>  "#49:0"
+
+m= params[:rid].load_rid.match.out( HasUnterlying ).node( as: :u )
+m.to_s
+ => "MATCH { type: strategie, rid: #49:0 }.out('has_underlying'){ as: u } RETURN u "
+```
+## Low Level Database Requests
 The **second Layer** handles Database-Requests.  
 In its actual implementation, these requests are delegated to the HTTP/JSON-API.
 
@@ -85,37 +210,36 @@ In its actual implementation, these requests are delegated to the HTTP/JSON-API.
 The database-handle is always present through `Arcade::Init.db`
 
 ```ruby
-DB =  Arcade::Init.db
+db =  Arcade::Init.db
 
-$ DB.get nn, mm                                 # returns a Aracde:Base object
+$ db.get nn, mm  # nn=2; mm=0                   # returns a Aracde:Base object
                                                 # rid is either "#11:10:" or two numbers
-$ DB.query querystring                          # returns either an Array of results (as  Hash) 
-$ DB.execute { querystring }                    # 
-$ DB.create <name>, attribute: value ....       # Creates a new <Document | Vertex> and returns the rid
+$ db.query querystring                          # returns either an Array of results (as  Hash) 
+$ db.execute { querystring }                    # execute a non idempotent query within a (nested) transaction
+$ db.create <name>, attribute: value ....       # Creates a new <Document | Vertex> and returns the rid
                                                 # Operation is performed as Database-Transaction and is rolled back on error
-$ DB.insert <name>, attribute: value ....       # Inserts a new <Document | Vertex> and returns the rid
-$ DB.create_edge <name>, from: <rid> or [rid, rid, ..] , to: <rid> or [rid, rid, ..]
+$ db.insert <name>, attribute: value ....       # Inserts a new <Document | Vertex> and returns the new object
+$ db.create_edge <name>, from: <rid> or [rid, rid, ..] , to: <rid> or [rid, rid, ..]
 
-DB.query " Select from person where age > 40 "
-DB.execute { " Update person set name='Hubert' return after $current where age = 36 " }
 ```
 
 **Convert database input to Arcade::Base Models**
 
-Either  `DB.query` or  `DB.execute` return the raw JSON-input from the database. It can always converted to model-objects by chaining
-`allocatet_model`.
+Either  `db.query` or  `db.execute` return the raw JSON-input from the database. It can always converted to model-objects by chaining
+`allocate_model` or `select_result`.
 
 ```ruby
-$ DB.query "select from my_names limit 1"
+$ db.query "select from my_names limit 1"
 # which is identical to
-$ My::Names.query( limit: 1).query
+$ My::Names.query( limit: 1).execute
  => [{:@out=>0, :@rid=>"#225:6", :@in=>0, :@type=>"my_names", :@cat=>"v", :name=>"Zaber"}] 
 # then
-$ My::Names.query( limit: 1).query.allocate_model.to_human
+$ My::Names.query( limit: 1).execute.allocate_model.to_human
  => ["<my_names[#225:6]: name: Zaber>" ]
  # replaces the hash with a My::Names Object 
 ```
 
+
 The **Base Layer** implements a low level access to the database API. 
 
 ```ruby
@@ -217,21 +341,47 @@ Select a range of nodes and perform a mathematical operation
   -=> select median(note_count) from  ( traverse out(connects) from #52:0 while $depth < 100 )  where $depth>=50  
    =>   {:"median(note_count)"=>75.5 }
 ```
-## Include in your own project
 
-Until a gem is released, first clone the project and set up your project environment
+### Transactions
+
+Database-Transactions are largely encapsulated
+
 ```
-mkdir workspace && cd workspace
-git clone https://github.com/topofocus/arcadedb
-mkdir my-project && cd my-project
-bundle init
-cat "gem arcadedb, path='../arcadedb' " >> Gemfile
-bundle install && bundle upate
-cp ../arcadedb/config.yml .
-mkdir bin
-cp ../arcadedb/bin/console bin/
-````
+db =  Arcade::Init.db
+db.begin_transaction
+
+{ perform insert, update, query, etc tasks in the database }
+
+db.commit 
+
+# or
+
+db.rollback
+
+```
+### Audit proofed Bookings
 
+Although ArcadeDB is a mutable database, the ruby-Interface supports basic audit proofed transactions.
+Two specialized Database-Types are included:
+
+* Arcade::RevisionRecord –  A document class, intended to be embedded in Revision-Records
+* Arcade::Revision       –  A vertex-class with specialized `insert-` and `update-` methods
+
+If a vertex is based on `Arcade::Revision`, a `protocol`-property is included. Its initialised with a single `Arcade::RevisionRecord` Object. Each `update` adds an `Arcade::RevisionRecord` to the protocol stack.
+
+```ruby
+  m= Member.insert( name: "Hubert", 
+                 surname: "Hugo", 
+                   birth: Date.new( 1976,3,15  ) ) { 'record initiated' }
+
+  m.update( birth: Date.new( 1978,3,15  )  ) { "member provided correct date via mail"  }
+    
+  m.protocol  =>  Date    | User |  Action                                | old
+             --------------------------------------------------------------------------------
+             =>  1.1.2024 | root |  record initiated                      |
+             =>  1.2.2024 | root |  member provided correct date via mail | birth: "1976-3-15"
+
+```
 
 ## Contributing
 

data/arcade.yml

@@ -13,7 +13,7 @@
     user: root
     pass: topo1focus
 :admin:
-  :host: 10.247.8.109
+  :host: localhost
   :port: 2480
   :user: root
   :pass: topo1focus

data/bin/console

@@ -1,14 +1,15 @@
 #!/usr/bin/env ruby
-## loads the active-orient environment 
+## loads the arcadeDB environment
 ## and starts an interactive shell
 ##
-## Parameter:  
+## Parameter:
 ##	       production (p)
 ##	       development (d)  [default]
 ##	       test (t)
 require 'bundler/setup'
-require 'terminal-table'
+#require 'terminal-table'
 require 'zeitwerk'
+ProjectRoot =  Pathname.new( Dir.pwd ).parent
 require 'pastel'
 require 'arcade'
 #require 'pry'
@@ -66,10 +67,6 @@ def browse  db: Arcade::Api.databases.first , extended: false
 end
 
 
-
-
-
-
 include Arcade
 
 def help
@@ -106,21 +103,25 @@ end
 
 help
 e=  ARGV.empty? ? :development :  ARGV.last.downcase.to_sym
-## load test model files
-#require "#{__dir__}/../spec/model_helper"
-
 loader =  Zeitwerk::Loader.new
-loader.push_dir ("#{__dir__}/../spec/model")
+if e.to_s[0] == 't'
+  loader.push_dir ("#{__dir__}/../spec/model")
+else
+  loader.push_dir ("#{__dir__}/../lib/model")
+
+end
 loader.setup
 puts  "DB = Arcade::Database-instance"
 DB = Arcade::Init.connect e
 #require 'pry'
+#if e.to_s[0] == 't'
+#    DB.create_type :document, 'test_document'
+#    DB.create_type :vertex, :test_vertex
+#
+#end
 require 'irb'
 ARGV.clear
-#begin
+
 IRB.start(__FILE__)
-#rescue ArgumentError => e
-#  puts e
-##  retry
-#end
+
 #Pry.start(__FILE__)