ruby-kuzu 0.0.1

data/lib/kuzu/connection.rb

@@ -0,0 +1,51 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Kùzu connection class
+class Kuzu::Connection
+	extend Loggability
+
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Execute the given +query_string+ via the connection and return the
+	### Kuzu::Result. If a block is given, the result will instead be yielded to it,
+	### finished when it returns, and the return value of the block will be returned
+	### instead.
+	def query( query_string, &block )
+		result = self._query( query_string )
+		return Kuzu::Result.wrap_block_result( result, &block )
+	end
+
+
+	### Create a new Kuzu::PreparedStatement for the specified +query_string+.
+	def prepare( query_string )
+		return Kuzu::PreparedStatement.new( self, query_string )
+	end
+
+
+	### Executes the given +statement+ (a Kuzu::PreparedStatement) after binding
+	### the given +bound_variables+ to it.
+	def execute( statement, **bound_variables, &block )
+		statement.bind( **bound_variables )
+		return statement.execute
+	end
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		details = " threads:%d" % [
+			self.max_num_threads_for_exec,
+		]
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+end # class Kuzu::Connection

data/lib/kuzu/database.rb

@@ -0,0 +1,53 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Main Kùzu database class
+class Kuzu::Database
+	extend Loggability
+
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Return a connection to this database.
+	def connect
+		return Kuzu::Connection.new( self )
+	end
+
+
+	### Return +true+ if this database was created in read-only mode.
+	def read_only?
+		return self.config.read_only
+	end
+
+
+	### Returns +true+ if this database will automatically checkpoint when the size of
+	### the WAL file exceeds the `checkpoint_threshold`.
+	def auto_checkpointing?
+		return self.config.auto_checkpoint
+	end
+
+
+	### Returns +true+ if this database uses compression for data on disk.
+	def compression_enabled?
+		return self.config.enable_compression
+	end
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		details = " path:%p read-only:%p" % [
+			self.path,
+			self.read_only?,
+		]
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+end # class Kuzu::Database

data/lib/kuzu/node.rb

@@ -0,0 +1,46 @@
+# -*- ruby -*-
+
+require 'forwardable'
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Kuzu node class
+class Kuzu::Node
+	extend Loggability,
+		Forwardable
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Create a new Node with the given +id+, +label+, and +properties+.
+	def initialize( id, label, **properties )
+		@id = id
+		@label = label
+		@properties = properties
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The internal id value of the given node
+	attr_reader :id
+
+	##
+	# The label value of the given node
+	attr_reader :label
+
+	##
+	# The Hash of the Node's properties, keyed by name as a Symbol
+	attr_reader :properties
+
+
+	# Allow direct access to properties
+	def_delegators :@properties, :[], :[]=, :dig
+
+end # class Kuzu::Node

data/lib/kuzu/prepared_statement.rb

@@ -0,0 +1,42 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# A parameterized query which can avoid planning the same query for repeated execution
+class Kuzu::PreparedStatement
+	extend Loggability
+
+	# Loggability API -- Use Kuzu's logger
+	log_to :kuzu
+
+
+	### Execute the statement against its connection and return a Kuzu::Result.
+	### If a +block+ is supplied, the result will be passed to it instead,
+	### then finished automatically, and the return value of the block returned
+	### instead.
+	def execute( **bound_variables, &block )
+		self.bind( **bound_variables )
+		result = self._execute
+		return Kuzu::Result.wrap_block_result( result, &block )
+	end
+
+
+	### Execute the statement against its connection and return `true` if it
+	### succeeded.
+	def execute!( **bound_variables )
+		self.bind( **bound_variables )
+		return self._execute!
+	end
+
+
+	### Bind the variables in the specified +variable_map+ to the statement.
+	def	bind( **variable_map )
+		variable_map.each do |name, value|
+			self.bind_variable( name, value )
+		end
+	end
+
+end # class Kuzu::PreparedStatement

data/lib/kuzu/query_summary.rb

@@ -0,0 +1,28 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Kùzu query summary class
+class Kuzu::QuerySummary
+	extend Loggability
+
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		details = " compiling: %0.3fs  execution: %0.3fs" % [
+			self.compiling_time,
+			self.execution_time,
+		]
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+end # class Kuzu::QuerySummary

data/lib/kuzu/recursive_rel.rb

@@ -0,0 +1,37 @@
+# -*- ruby -*-
+
+require 'forwardable'
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Kuzu recursive relationship class
+class Kuzu::RecursiveRel
+	extend Loggability,
+		Forwardable
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Create a new RecursiveRel with the given +nodes+ and +rels+.
+	def initialize( nodes, rels )
+		@nodes = nodes
+		@rels = rels
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The Array of Kuzu::Nodes in the chain
+	attr_reader :nodes
+
+	##
+	# The Array of Kuzu::Rels connecting the Nodes in the chain
+	attr_reader :rels
+
+end # class Kuzu::RecursiveRel

data/lib/kuzu/rel.rb

@@ -0,0 +1,51 @@
+# -*- ruby -*-
+
+require 'forwardable'
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Kuzu rel (relationship) class
+class Kuzu::Rel
+	extend Loggability,
+		Forwardable
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Create a new Rel with the given +id+, +label+, and +properties+.
+	def initialize( src_id, dst_id, label, **properties )
+		@src_id = src_id
+		@dst_id = dst_id
+		@label = label
+		@properties = properties
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The internal id value of the source node
+	attr_reader :src_id
+
+	##
+	# The internal id value of the destination node
+	attr_reader :dst_id
+
+	##
+	# The label value of the given node
+	attr_reader :label
+
+	##
+	# The Hash of the Rel's properties, keyed by name as a Symbol
+	attr_reader :properties
+
+
+	# Allow direct access to properties
+	def_delegators :@properties, :[], :[]=, :dig
+
+end # class Kuzu::Rel

data/lib/kuzu/result.rb

@@ -0,0 +1,139 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require 'kuzu' unless defined?( Kuzu )
+
+
+# Kùzu query result class
+class Kuzu::Result
+	extend Loggability
+
+
+	# Loggability API -- log to Kuzu's logger
+	log_to :kuzu
+
+
+	### Execute the given +query+ via the specified +connection+ and return the
+	### Kuzu::Result. If a block is given, the result will instead be yielded to it,
+	### finished when it returns, and the return value of the block will be returned
+	### instead.
+	def self::from_query( connection, query, &block )
+		return connection.query( query, &block )
+	end
+
+
+	### Execute the given +statement+ and return the Kuzu::Result. If a block is given,
+	### the result will instead be yielded to it, finished when it returns, and the
+	### return value of the block will be returned instead.
+	def self::from_prepared_statement( statement, &block )
+		return statement.execute( &block )
+	end
+
+
+	### If the +block+ is provided, yield +result+ to it and then call #finish on it,
+	### returning the +block+ result. If +block+ is not given, just return +result+.
+	def self::wrap_block_result( result, &block )
+		return result unless block
+
+		begin
+			rval = block.call( result )
+		ensure
+			result.finish
+		end
+
+		return rval
+	end
+
+
+	### Fetch the names of the columns in the result as an Array of Strings.
+	def	column_names
+		return @column_names ||= self.get_column_names
+	end
+
+
+	### Return a Kuzu::QuerySummary for the query that generated the Result.
+	def query_summary
+		return Kuzu::QuerySummary.from_result( self )
+	end
+
+
+	### Get the next tuple of the result as a Hash.
+	def next
+		pairs = self.column_names.zip( self.get_next_values )
+		return Hash[ pairs ]
+	end
+
+
+	### Iterate over each tuple of the result, yielding it to the +block+. If no
+	### +block+ is given, return an Enumerator that will yield them instead.
+	def	each( &block )
+		enum = self.tuple_enum
+		return enum.each( &block ) if block
+		return enum
+	end
+
+
+	### Return the next result set after this one as a Kuzu::Result, or `nil`if
+	### there is no next set.
+	def next_set
+		return nil unless self.has_next_set?
+		return self.class.from_next_set( self )
+	end
+
+
+	### Iterate over each result set in the results, yielding it to the block. If
+	### no +block+ is given, return an Enumerator tht will yield each set as its own
+	### Result.
+	def each_set( &block )
+		enum = self.next_set_enum
+		return enum.each( &block ) if block
+		return enum
+	end
+
+
+	### Return a string representation of the receiver suitable for debugging.
+	def inspect
+		if self.finished?
+			details = " (finished)"
+		else
+			details = " success: %p (%d tuples of %d columns): %s" % [
+				self.success?,
+				self.num_tuples,
+				self.num_columns,
+				self.to_s,
+			]
+		end
+
+		default = super
+		return default.sub( />/, details + '>' )
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return an Enumerator that yields result tuples as Hashes.
+	def tuple_enum
+		return Enumerator.new do |yielder|
+			self.reset_iterator
+			while self.has_next?
+				tuple = self.next
+				yielder.yield( tuple )
+			end
+		end
+	end
+
+
+	def next_set_enum
+		result = self
+		return Enumerator.new do |yielder|
+			while result
+				yielder.yield( result )
+				result = result.next_set
+			end
+		end
+	end
+
+end # class Kuzu::Result

data/lib/kuzu.rb

@@ -0,0 +1,79 @@
+# -*- ruby -*-
+
+require 'loggability'
+
+require_relative 'kuzu_ext'
+
+#--
+# See also: ext/kuzu_ext/kuzu_ext.c
+module Kuzu
+	extend Loggability
+
+
+	# Library version
+	VERSION = '0.0.1'
+
+
+	# Set up a logger for Kuzu classes
+	log_as :kuzu
+
+
+	### Create and return a Kuzu::Database. If +path+ is +nil+, an empty string, or
+	### the Symbol :memory, creates an in-memory database. Valid options are:
+	###
+	### `:buffer_pool_size`
+	### :    Max size of the buffer pool in bytes.
+	###
+	### `:max_num_threads`
+	### :    The maximum number of threads to use during query execution.
+	###
+	### `:enable_compression`
+	### :    Whether or not to compress data on-disk for supported types
+	###
+	### `:read_only`
+	### :    If true, open the database in read-only mode. No write transaction is allowed on the
+	### Database object. If false, open the database read-write.
+	###
+	### `:max_db_size`
+	###	:    The maximum size of the database in bytes.
+	###
+	### `:auto_checkpoint`
+	### :    If true, the database will automatically checkpoint when the size of
+	### the WAL file exceeds the checkpoint threshold.
+	###
+	### `:checkpoint_threshold`
+	### :    The threshold of the WAL file size in bytes. When the size of the
+	### WAL file exceeds this threshold, the database will checkpoint if
+	### `auto_checkpoint` is true.
+	def self::database( path='', **config )
+		path = '' if path.nil? || path == :memory
+		self.log.info "Opening database %p" % [ path ]
+		return Kuzu::Database.new( path.to_s, **config )
+	end
+
+
+	### Return a Time object from the given +milliseconds+ epoch time.
+	def self::timestamp_from_timestamp_ms( milliseconds )
+		seconds, subsec = milliseconds.divmod( 1_000 )
+		return Time.at( seconds, subsec, :millisecond )
+	end
+
+
+	### Return a Time object from the given +microseconds+ epoch time and
+	### optional timezone offset in seconds via the +zone+ argument.
+	def self::timestamp_from_timestamp_us( microseconds, zone=nil )
+		seconds, subsec = microseconds.divmod( 1_000_000 )
+		return Time.at( seconds, subsec, :microsecond, in: zone )
+	end
+
+
+	### Return a Time object from the given +nanoseconds+ epoch time.
+	def self::timestamp_from_timestamp_ns( nanoseconds )
+		seconds, subsec = nanoseconds.divmod( 1_000_000_000 )
+		return Time.at( seconds, subsec, :nanosecond )
+	end
+
+end # module Kuzu
+
+# Fancy alias
+Kùzu = Kuzu

data/spec/kuzu/config_spec.rb

@@ -0,0 +1,98 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu/config'
+
+
+RSpec.describe( Kuzu::Config ) do
+
+	it "can be created with defaults" do
+		result = described_class.new
+
+		expect( result ).to be_a( described_class )
+
+		expect( result.buffer_pool_size ).to be_a( Integer )
+		expect( result.max_num_threads ).to be_a( Integer )
+		expect( result.enable_compression ).to eq( true )
+		expect( result.read_only ).to eq( false )
+		expect( result.max_db_size ).to be_a( Integer )
+		expect( result.auto_checkpoint ).to eq( true )
+		expect( result.checkpoint_threshold ).to be_a( Integer )
+	end
+
+
+	it "can set its buffer_pool_size" do
+		instance = described_class.new
+
+		expect {
+			instance.buffer_pool_size = 2 ** 11
+		}.to change { instance.buffer_pool_size }.to( 2 ** 11 )
+	end
+
+
+	it "can set its max_num_threads" do
+		instance = described_class.new
+
+		expect {
+			instance.max_num_threads = 4
+		}.to change { instance.max_num_threads }.to( 4 )
+	end
+
+
+	it "can disable compression" do
+		instance = described_class.new
+
+		expect {
+			instance.enable_compression = false
+		}.to change { instance.enable_compression }.to( false )
+	end
+
+
+	it "can set read-only mode" do
+		instance = described_class.new
+
+		expect {
+			instance.read_only = true
+		}.to change { instance.read_only }.to( true )
+	end
+
+
+	it "can set read-only mode using a truthy value" do
+		instance = described_class.new
+
+		expect {
+			instance.read_only = :yep
+		}.to change { instance.read_only }.to( true )
+	end
+
+
+	it "can set its max_db_size" do
+		instance = described_class.new
+
+		expect {
+			instance.max_db_size = 2 ** 21
+		}.to change { instance.max_db_size }.to( 2 ** 21 )
+	end
+
+
+	it "can disable auto-checkpointing" do
+		instance = described_class.new
+
+		expect {
+			instance.auto_checkpoint = false
+		}.to change { instance.auto_checkpoint }.to( false )
+	end
+
+
+	it "can set its checkpoint threshold" do
+		instance = described_class.new
+
+		expect {
+			instance.checkpoint_threshold = 2 ** 22
+		}.to change { instance.checkpoint_threshold }.to( 2 ** 22 )
+	end
+
+
+end
+

data/spec/kuzu/database_spec.rb

@@ -0,0 +1,51 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu/database'
+
+
+RSpec.describe( Kuzu::Database ) do
+
+	let( :spec_tmpdir ) do
+		tmpfile_pathname()
+	end
+
+	let( :db_path ) { spec_tmpdir + 'spec_db' }
+
+
+	it "can be created in-memory" do
+		instance = described_class.new( '' )
+		expect( instance ).to be_a( described_class )
+	end
+
+
+	it "can be created read-only from an existing on-disk database" do
+		original = described_class.new( db_path.to_s )
+
+		ro = described_class.new( db_path.to_s, read_only: true )
+		expect( ro ).to be_read_only
+	end
+
+
+	it "can be created without auto-checkpointing" do
+		instance = described_class.new( db_path.to_s, auto_checkpoint: false )
+		expect( instance ).not_to be_auto_checkpointing
+	end
+
+
+	it "can be created without compression" do
+		instance = described_class.new( db_path.to_s, enable_compression: false )
+		expect( instance ).not_to be_compression_enabled
+	end
+
+
+	it "can create a connection to itself" do
+		instance = described_class.new( db_path.to_s, enable_compression: false )
+
+		result = instance.connect
+
+		expect( result ).to be_a( Kuzu::Connection )
+	end
+
+end