arcadedb 0.5.0 → 0.5.4

data/lib/arcade/timeseries.rb

@@ -0,0 +1,211 @@
+module Arcade
+  # Abstraction of ArcadeDB's native TimeSeries types.
+  #
+  # A TimeSeries type is not a vertex/document: it has no rid and carries no edges.
+  # Membership is expressed through tags, values through typed fields.
+  #
+  #   class Ohlcv < Arcade::Timeseries
+  #     timestamp :ts, precision: :second
+  #     tags   symbol: String, currency: String
+  #     fields open: Float, high: Float, low: Float, close: Float, volume: Integer
+  #   end
+  #
+  #   Ohlcv.create_type
+  #   Ohlcv.write symbol: 'SAPX:GER', ts: Date.today, open: 1, high: 2, low: 0.5, close: 1.5, volume: 100
+  #   Ohlcv.range from: '2026-01-01', tags: { symbol: 'SAPX:GER' }
+  #   Ohlcv.latest tags: { symbol: 'SAPX:GER' }
+  #   Ohlcv.bucket '7d', from: '2026-01-01', aggregate: { close: :last, volume: :sum }
+  #
+  # Conventions:
+  # * Writes go through the InfluxDB Line Protocol endpoint (fastest remote path);
+  #   reads go through SQL (range pushdown, ts.* functions).
+  # * Timestamps are accepted as Time, DateTime, Date, ISO-String or epoch Numeric
+  #   and normalised to the declared precision — never pass raw numbers of a
+  #   different unit than declared, the engine will not complain but read wrong.
+  # * The server's DELETE on timeseries types reports a count but leaves the rows
+  #   (ArcadeDB 26.10.1) — there is deliberately no window-replace helper here.
+  #   Re-writing a timestamp appends a second sample; deduplicate on read if needed.
+  class Timeseries < Base
+
+    TYPES = { String => 'STRING', Float => 'DOUBLE', Integer => 'LONG',
+              :bool => 'BOOLEAN', :datetime => 'DATETIME' }.freeze
+
+    # SQL keyword and nanosecond-multiplier per supported precision
+    PRECISIONS = { second:      ['SECOND',      1],
+                   millisecond: ['MILLISECOND', 1_000],
+                   microsecond: ['MICROSECOND', 1_000_000],
+                   nanosecond:  ['NANOSECOND',  1_000_000_000] }.freeze
+
+    LP_PRECISION = { second: 's', millisecond: 'ms', microsecond: 'us', nanosecond: 'ns' }.freeze
+
+    # ts.<fn>(field, ts) where the engine needs the timestamp, plain SQL otherwise
+    AGGREGATES = { last:  ->(f, ts){ "ts.last(#{ f }, #{ ts })" },
+                   first: ->(f, ts){ "ts.first(#{ f }, #{ ts })" },
+                   avg:   ->(f, _){ "avg(#{ f })" },
+                   sum:   ->(f, _){ "sum(#{ f })" },
+                   min:   ->(f, _){ "min(#{ f })" },
+                   max:   ->(f, _){ "max(#{ f })" },
+                   count: ->(f, _){ "count(#{ f })" } }.freeze
+
+    class << self
+
+      # ---- schema declaration -----------------------------------------------------------
+
+      def timestamp name = nil, precision: nil, shards: nil, retention: nil
+        if name.nil? && precision.nil?          # getter use:  ts_name via timestamp()
+          @ts_name ||= :ts
+          @ts_precision ||= :second
+          return @ts_name
+        end
+        @ts_name, @ts_precision = name, (precision || :second)
+        @ts_shards, @ts_retention = shards, retention
+      end
+
+      def tags spec = nil
+        @ts_tags = spec if spec
+        @ts_tags ||= {}
+      end
+
+      def fields spec = nil
+        @ts_fields = spec if spec
+        @ts_fields ||= {}
+      end
+
+      def ts_name       = timestamp
+      def ts_precision  = @ts_precision ||= :second
+      def type_name     = database_name
+
+      # ---- type lifecycle ---------------------------------------------------------------
+
+      def create_type
+        return true if type_exists?
+        tag_cols  = tags.map  { |k, t| "#{ k } #{ sql_type t }" }.join(', ')
+        field_cols = fields.map { |k, t| "#{ k } #{ sql_type t }" }.join(', ')
+        cmd = "CREATE TIMESERIES TYPE #{ type_name } " \
+              "TIMESTAMP #{ ts_name } PRECISION #{ PRECISIONS[ts_precision].first } " \
+              "TAGS (#{ tag_cols }) FIELDS (#{ field_cols })"
+        cmd += " SHARDS #{ @ts_shards }"   if @ts_shards
+        cmd += " RETENTION #{ @ts_retention }" if @ts_retention
+        result = db.transmit { cmd }
+        # the engine registers the type asynchronously — wait until readable
+        # (writes immediately after create otherwise fail with unknownTypes)
+        10.times { break if type_exists?; sleep 0.2 }
+        result
+      end
+
+      # NB: schema:types does NOT list timeseries types on 26.10 —
+      # probe the ts/query endpoint instead (400 unknownTypes = absent).
+      def type_exists?
+        Api.post_json "ts/#{ db.database }/query", { type: type_name.to_s }
+        true
+      rescue Arcade::QueryError
+        false
+      end
+
+      def drop_type
+        db.transmit { "DROP TIMESERIES TYPE #{ type_name }" }
+      end
+
+      # ---- writing ----------------------------------------------------------------------
+
+      # one sample:  Ohlcv.write symbol: 'SAP', ts: Date.today, close: 1.5
+      def write **sample
+        write_many [sample]
+      end
+
+      # batch: array of hashes, one per sample (Line Protocol, precision param matches class)
+      def write_many samples
+        return 0 if samples.empty?
+        lines = samples.map { |s| line_for s }
+        Api.post_text "ts/#{ db.database }/write?precision=#{ LP_PRECISION[ts_precision] }", lines.join("\n")
+      end
+
+      # ---- reading ----------------------------------------------------------------------
+
+      # raw samples within [from, to] (both optional), filtered by tag equality
+      def range from: nil, to: nil, tags: {}, columns: nil, limit: nil
+        projections = columns ? ([ts_name] + Array(columns)).join(', ') : '*'
+        conditions  = []
+        conditions << "#{ ts_name } >= #{ sql_time from }" if from
+        conditions << "#{ ts_name } <= #{ sql_time to }"   if to
+        tags.each { |k, v| conditions << "#{ k } = '#{ v }'" }
+        sql = "SELECT #{ projections } FROM #{ type_name }"
+        sql += " WHERE #{ conditions.join ' AND ' }" unless conditions.empty?
+        sql += " ORDER BY #{ ts_name }"
+        sql += " LIMIT #{ limit }" if limit
+        db.transmit { sql }
+      end
+
+      # the most recent sample, via the dedicated latest-endpoint
+      # returns a Hash of column => value (nil when the series is empty)
+      def latest tags: {}
+        query = "ts/#{ db.database }/latest?type=#{ type_name }"
+        query += "&tag=#{ tags.first.join ':' }" unless tags.empty?
+        answer = Api.get_json query
+        return nil if answer[:latest].nil?
+        answer[:columns].map.with_index { |col, i| [ col.to_sym, answer[:latest][i] ] }.to_h
+      end
+
+      # time-bucketed aggregation, e.g. weekly candles:
+      #   Ohlcv.bucket '7d', aggregate: { close: :last, high: :max, low: :min, volume: :sum }
+      def bucket interval, from: nil, to: nil, tags: {}, aggregate: {}
+        measures = aggregate.map do |field, fn|
+          "#{ AGGREGATES.fetch(fn).call(field, ts_name) } as #{ field }_#{ fn }"
+        end.join(', ')
+        conditions  = []
+        conditions << "#{ ts_name } >= #{ sql_time from }" if from
+        conditions << "#{ ts_name } <= #{ sql_time to }"   if to
+        tags.each { |k, v| conditions << "#{ k } = '#{ v }'" }
+        sql = "SELECT ts.timeBucket('#{ interval }', #{ ts_name }) as `bucket`"
+        sql += ", #{ measures }" unless measures.empty?
+        sql += " FROM #{ type_name }"
+        sql += " WHERE #{ conditions.join ' AND ' }" unless conditions.empty?
+        sql += " GROUP BY `bucket` ORDER BY `bucket`"
+        db.transmit { sql }
+      end
+
+      private
+
+      # ---- normalisation ------------------------------------------------------------------
+
+      def sql_type type
+        TYPES.fetch(type) { type.to_s.upcase }
+      end
+
+      # sample hash -> InfluxDB line, epoch normalised to the declared precision
+      def line_for sample
+        stamp = to_epoch sample[ts_name] || sample[ts_name.to_s]
+        raise ArgumentError, "#{ type_name }: missing timestamp '#{ ts_name }'" if stamp.nil?
+        tag_part   = tags.keys.map   { |t| "#{ t }=#{ escape_tag sample[t] }" }.join(',')
+        field_part = fields.keys.map  { |f| "#{ f }=#{ sample[f] }" }.join(',')
+        "#{ type_name },#{ tag_part } #{ field_part } #{ stamp }"
+      end
+
+      def to_epoch value
+        seconds = case value
+                  when Time then value.to_i
+                  when Numeric then value.to_i          # already epoch seconds
+                  when Date then Time.utc(value.year, value.month, value.day).to_i
+                  when String then Time.parse(value).to_i
+                  else nil end
+        return nil if seconds.nil?
+        seconds * PRECISIONS[ts_precision].last
+      end
+
+      def sql_time value
+        t = case value
+            when Time then value
+            when Date then Time.utc(value.year, value.month, value.day)
+            when String then Time.parse(value, in: 'UTC')
+            when Numeric then Time.at(value)
+            else raise ArgumentError, "unsupported time: #{ value.inspect }" end
+        "'#{ t.utc.strftime('%Y-%m-%d %H:%M:%S') }'"
+      end
+
+      def escape_tag value
+        value.to_s.gsub(/([,= ])/) { '\\' + $1 }
+      end
+
+    end
+  end
+end

data/lib/arcade/version.rb

@@ -1,3 +1,3 @@
 module Arcade
-  VERSION = "0.5.0"
+  VERSION = "0.5.4"
 end

data/lib/arcade.rb

@@ -9,13 +9,13 @@ require "dry/core/class_builder"
 require "dry/core/class_attributes"
 require 'json'
 
-module Types
-  include Dry.Types()
-end
+require_relative '../lib/types'
+#module Types
+#  include Dry.Types()
+#end
 require 'yaml'
 require 'securerandom'
 require 'httpx'
-require 'arcade/errors'
 require_relative '../lib/arcade/support/object'
 require_relative '../lib/arcade/support/string'
 require_relative '../lib/arcade/support/class'
@@ -24,13 +24,16 @@ require_relative '../lib/arcade/support/model'
 require_relative '../lib/arcade/support/conversions'
 require_relative '../lib/arcade/api/primitives'
 require_relative '../lib/arcade/api/operations'
+require_relative '../lib/arcade/errors'
 require_relative '../lib/arcade/base'
 require_relative '../lib/arcade/logging'
 require_relative '../lib/arcade/config'
 require_relative '../lib/arcade/database'
 require_relative '../lib/arcade/match'
 require_relative '../lib/arcade/query'
+require_relative '../lib/arcade/timeseries'
 require_relative '../lib/arcade/init'
+require_relative '../lib/arcade/rag_schema'
 require_relative "../lib/models"
 require_relative '../lib/railtie'  if defined? Rails::Railtie
 

data/lib/model/document.rb

@@ -11,7 +11,7 @@ module Arcade
    end
 
 =begin
-    Document.delete fires a "delete vertex" command to the database.
+    Document.delete fires a "delete" command to the database.
     To remove all records  use  »all: true« as argument
 
     The "where" parameter is optional

data/lib/model/edge.rb

@@ -27,6 +27,23 @@ module Arcade
 
     end
 
+
+    ## class-method: Delete Edge between two vertices
+    ##
+    ## returns the count of deleted edges
+    ##
+    ## todo: add conditions
+    def self.delete from:, to:
+      return 0 if from.nil? || to.nil?
+      raise "parameter ( from: ) must be a String or a Vertex" unless from.is_a?(String) || from.is_a?( Arcade::Vertex)
+      raise "parameter ( to: ) must be a String or a Vertex" unless to.is_a?(String) || to.is_a?( Arcade::Vertex)
+      raise "parameters (from: + to:) must respond to `.rid`" unless from.respond_to?( :rid) && to.respond_to?(:rid)
+
+      db.execute{ "delete edge from #{from.rid} to #{to.rid} " } &.select_result &.first
+    end
+
+
+    ## instance method: Delete specified edge
     def delete
       db.execute{  "delete edge #{ rid }" }.select_result
     end

data/lib/model/revision.rb

@@ -0,0 +1,41 @@
+module Arcade
+  class  Revision < Arcade::Vertex
+    attribute :protocol?, Types::Nominal::Array
+
+    @@u='root'  # default user
+    @@i = 'Record initiated'
+
+  def self.set_user u
+    @@u = u
+  end
+
+  def self.set_initial_message m
+    @@i = m
+  end
+
+  def self.insert **attr
+
+    action = block_given? ?  yield : @@i
+    i= super **attr
+    i.update_list :protocol,
+                   Arcade::RevisionRecord.create( user: @@u, action: action ),
+                   modus: :first
+    i.refresh
+
+  end
+
+
+  def update **attr
+    hist_state =  attr.keys.map do |k|
+                  [ k,  send( k ) ]
+    end.to_h
+    super **attr
+    revision = if block_given?
+         Arcade::RevisionRecord.create( user: @@u, action: yield,  fields: hist_state )
+               else
+                 Arcade::RevisionRecord.create( fields: hist_state )
+               end
+    update_list :protocol, revision, modus: :append
+  end
+  end
+end

data/lib/model/revision_record.rb

@@ -0,0 +1,29 @@
+module Arcade
+  class RevisionRecord  < Document
+    attribute  :user, Types::Nominal::String.default( 'root'.freeze )
+    attribute  :action, Types::Nominal::String.default( "Property changed".freeze )
+    attribute  :date, Types::Nominal::Date.default( Date.today.freeze )
+    attribute  :fields?, Types::Nominal::Hash
+
+   #  Revision Records are always embedded.
+   #  create and insert methods return an new ruby record
+   def self.create **attr
+     new **( { rid: '#0:0', date: Date.today}.merge attr )
+   end
+   def self.insert **attr
+     new **( { rid: '#0:0', date: Date.today}.merge **attr )
+   end
+
+=begin
+  Its not allowed to delete records.
+=end
+    def self.delete where: {} , **args
+      raise ArcadeQueryError, "Its not possible to delete revision records"
+    end
+
+    def delete
+      raise ArcadeQueryError, "Its not possible to delete revision records"
+    end
+
+  end
+end

data/lib/model/timeseries.rb

@@ -0,0 +1,6 @@
+module Arcade
+  class Timeseries < Arcade::Base
+    # base class for user model classes; behaviour lives in Arcade::Timeseries (lib/arcade/timeseries.rb)
+    # the constant Arcade::Timeseries IS this class — the arcade-side file reopens it with full behaviour.
+  end
+end

data/lib/model/vertex.rb

@@ -213,6 +213,50 @@ or
     nil
   end
 
+=begin
+----------------------------------- Match ------------------------------------------
+(ClassMethod)
+
+Creates a Match-Statement based on the vertex type
+
+```
+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 "
+```
+=end
+  def self.match **args
+       as = args.delete( :as) || :a
+       args = args.delete( :where ) if args.key?( :where )
+       Arcade::Match.new type: self,  where: args, as: as
+  end
+
+=begin
+----------------------------------- Match ------------------------------------------
+(InstanceMethod)
+
+Creates a Match-Statement based on the current vertex ( i.e  as response to a website-request )
+
+```
+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 "
+```
+=end
+  def match as: nil
+    if as.nil?
+      Arcade::Match.new vertex: self
+    else
+      Arcade::Match.new vertex: self, as: as
+    end
+  end
 
   def remove
     db.execute{ "delete vertex #{rid}" }
@@ -224,7 +268,7 @@ Format: < Classname: Edges, Attributes >
 =end
 	def to_human
 
-    in_and_out =  "{#{inE.count}->}{->#{outE.count }}, "
+    in_and_out =  coe.then{| i,o| "{#{i}->}{->#{o}}, "}
 
 		#Default presentation of Arcade::Base::Model-Objects
 
@@ -244,6 +288,13 @@ Format: < Classname: Edges, Attributes >
 	end
 
 
+ # Count Of Edges (coe)
+ # returns an Array: [ count-of-in-edges, count-of-out-edges ]
+   def coe 
+      db.query( "select in().size() as ie, out().size() as oe from #{rid}" ) &.first.values
+   end
+	            
+
     def refresh
       # force reloading of edges and nodes
       # edges are not cached (now)

data/lib/models.rb

@@ -1,6 +1,9 @@
 require_relative "../lib/model/document.rb"
+require_relative "../lib/model/revision_record.rb"
 require_relative "../lib/model/vertex.rb"
 require_relative "../lib/model/edge.rb"
+require_relative "../lib/model/revision.rb"
 require_relative "../lib/model/basicvertex.rb"
 require_relative "../lib/model/basicdocument.rb"
 require_relative "../lib/model/basicedge.rb"
+require_relative "../lib/model/timeseries.rb"

data/lib/types.rb

@@ -0,0 +1,35 @@
+module Types
+  include Dry.Types()
+
+  # include in attribute definitions
+  Rid = String.constrained( format:  /\A[#]{1}[0-9]{1,}:[0-9]{1,}\z/ )
+  Blockchain =  String.constrained( format: /^(algo|eth|btc)$/ )  #  add other blockchain symbols here
+  Email = String.constrained( format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i )
+
+
+  # Define a type for your DateTime with timezone.  Crucially, use
+# the `.constructor` to handle the string parsing and potential errors. (source: Gemini)
+Types::DateTime = Types::Any.constructor do |value|
+  begin
+    case value
+      when String
+    ::DateTime.parse(value)
+      when Integer
+      ::Time.at(value).to_datetime
+      else
+      ::DateTime.now
+    end
+  rescue ArgumentError
+    # Handle invalid date strings.  Options:
+    # 1. Raise an exception (recommended for API responses)
+    raise Dry::Types::CoercionError.new(
+      value, DateTime, "Invalid DateTime format: #{value}"
+    )
+    # 2. Return nil (less strict, but might lead to unexpected behavior)
+    # nil
+    # 3. Use a default value (be careful with this, as it might mask errors)
+    # DateTime.now
+  end
+end
+
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: arcadedb
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.4
 platform: ruby
 authors:
 - Hartmut Bischoff
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-12-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -134,6 +133,7 @@ files:
 - Gemfile.lock
 - Guardfile
 - LICENSE
+- RAG_SCHEMA.md
 - README.md
 - Rakefile
 - arcade.yml
@@ -141,6 +141,8 @@ files:
 - bin/+
 - bin/console
 - examples/books.rb
+- examples/rag_example.rb
+- examples/rag_usecase_demo.rb
 - examples/relation_1__1.rb
 - examples/relation_1__n.rb
 - examples/relation_n_n.rb
@@ -158,20 +160,26 @@ files:
 - lib/arcade/logging.rb
 - lib/arcade/match.rb
 - lib/arcade/query.rb
+- lib/arcade/rag_schema.rb
 - lib/arcade/support/class.rb
 - lib/arcade/support/conversions.rb
 - lib/arcade/support/model.rb
 - lib/arcade/support/object.rb
 - lib/arcade/support/sql.rb
 - lib/arcade/support/string.rb
+- lib/arcade/timeseries.rb
 - lib/arcade/version.rb
 - lib/model/basicdocument.rb
 - lib/model/basicedge.rb
 - lib/model/basicvertex.rb
 - lib/model/document.rb
 - lib/model/edge.rb
+- lib/model/revision.rb
+- lib/model/revision_record.rb
+- lib/model/timeseries.rb
 - lib/model/vertex.rb
 - lib/models.rb
+- lib/types.rb
 - rails.md
 - rails/arcade.rb
 - rails/config.yml
@@ -180,7 +188,6 @@ homepage: https://github.com/topofocus/arcadedb
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -195,8 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key: 
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Ruby Interface to ArcadeDB
 test_files: []