ruby-kuzu 0.0.1

data/spec/kuzu/prepared_statement_spec.rb

@@ -0,0 +1,93 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu/prepared_statement'
+
+
+RSpec.describe( Kuzu::PreparedStatement ) do
+
+	let( :db ) { Kuzu.database }
+	let( :connection ) { db.connect }
+
+	let( :schema ) { load_test_data( 'demo-db/schema.cypher' ) }
+	let( :copy_statements ) { load_test_data( 'demo-db/copy.cypher' ) }
+
+
+	def setup_demo_db
+		connection.run( schema )
+		connection.run( copy_statements )
+	end
+
+
+	before( :each ) do
+		setup_demo_db()
+	end
+
+
+	#
+	# Specs
+	#
+
+	it "can be created via a connection and a query string" do
+		statement = described_class.new( connection, <<~END_OF_QUERY )
+			MATCH (u:User)
+		    WHERE u.age > $min_age and u.age < $max_age
+		    RETURN u.name
+		END_OF_QUERY
+
+		expect( statement ).to be_a( described_class )
+		expect( statement ).to be_success
+		expect( statement.connection ).to be( connection )
+	end
+
+
+	it "doesn't error if executed before its variables are bound" do
+		statement = described_class.new( connection, <<~END_OF_QUERY )
+			MATCH (u:User)
+		    WHERE u.age > $min_age and u.age < $max_age
+		    RETURN u.name
+		END_OF_QUERY
+
+		result = statement.execute
+
+		expect( result.num_tuples ).to eq( 0 )
+
+		result.finish
+	end
+
+
+	it "can be executed if all of its variables are bound" do
+		statement = described_class.new( connection, <<~END_OF_QUERY )
+		MATCH (u:User)
+		WHERE u.age >= $min_age and u.age <= $max_age
+		RETURN u.name
+		END_OF_QUERY
+
+		result = statement.execute( min_age: 40, max_age: 50 )
+
+		expect( result.num_tuples ).to eq( 2 )
+
+		result.finish
+	end
+
+
+	it "can be reused" do
+		statement = described_class.new( connection, <<~END_OF_QUERY )
+		MATCH (u:User)
+		WHERE u.age >= $min_age and u.age <= $max_age
+		RETURN u.name
+		END_OF_QUERY
+
+		result = statement.execute( min_age: 40, max_age: 50 )
+		expect( result ).to be_success
+		expect( result.num_tuples ).to eq( 2 )
+		result.finish
+
+		result = statement.execute( min_age: 5, max_age: 90 )
+		expect( result ).to be_success
+		expect( result.num_tuples ).to eq( 4 )
+		result.finish
+	end
+
+end

data/spec/kuzu/query_summary_spec.rb

@@ -0,0 +1,30 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu/query_summary'
+
+
+RSpec.describe( Kuzu::QuerySummary ) do
+
+	CREATE_TABLE_STATEMENTS = [
+		'CREATE NODE TABLE User(name STRING, age INT64, PRIMARY KEY (name))',
+		'CREATE NODE TABLE City(name STRING, population INT64, PRIMARY KEY (name))',
+	]
+
+
+	let( :db ) { Kuzu.database }
+	let( :connection ) { db.connect }
+
+
+	it "can return a summary of its query's timing" do
+		connection.query( CREATE_TABLE_STATEMENTS.first ) do |result|
+			summary = result.query_summary
+
+			expect( summary ).to be_a( described_class )
+			expect( summary.compiling_time ).to be_a( Float ).and( be > 0.0 )
+			expect( summary.execution_time ).to be_a( Float ).and( be > 0.0 )
+		end
+	end
+
+end

data/spec/kuzu/result_spec.rb

@@ -0,0 +1,190 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu/result'
+
+
+RSpec.describe( Kuzu::Result ) do
+
+	let( :db ) { Kuzu.database }
+	let( :connection ) { db.connect }
+
+	let( :schema ) { load_test_data( 'demo-db/schema.cypher' ) }
+	let( :copy_statements ) { load_test_data( 'demo-db/copy.cypher' ) }
+
+
+	def setup_demo_db
+		connection.run( schema )
+		connection.run( copy_statements )
+	end
+
+
+	#
+	# Specs
+	#
+
+	describe "query constructor" do
+
+		it "can be created via a simple query" do
+			result = described_class.from_query( connection, schema.each_line.first )
+
+			expect( result ).to be_a( described_class )
+			expect( result ).to be_success
+
+			result.finish
+		end
+
+
+		it "automatically finishes the result when run with a block" do
+			block_result = nil
+
+			described_class.from_query( connection, schema.each_line.first ) do |result|
+				block_result = result
+				expect( result ).to be_a( described_class )
+				expect( result ).to be_success
+			end
+
+			expect( block_result ).to be_finished
+		end
+
+
+		it "can return a summary of its query's timing" do
+			result = described_class.from_query( connection, schema.each_line.first )
+			summary = result.query_summary
+
+			expect( summary ).to be_a( Kuzu::QuerySummary )
+
+			result.finish
+		end
+
+
+		it "can return the error message if there was a problem with the query" do
+			expect {
+				described_class.from_query( connection, "FOOBANGLE NERFRIDER" )
+			}.to raise_error( Kuzu::QueryError, /parser exception/i )
+		end
+
+
+		it "can iterate over result tuples" do
+			setup_demo_db()
+
+			result = described_class.from_query( connection, <<~END_OF_QUERY )
+				MATCH ( a:User )-[ f:Follows ]->( b:User )
+			    RETURN a.name, b.name, f.since;
+			END_OF_QUERY
+
+			expect( result ).to be_a( described_class )
+			expect( result ).to be_success
+			expect( result.num_columns ).to eq( 3 )
+			expect( result.column_names ).to eq([ "a.name", "b.name", "f.since" ])
+			expect( result.each.to_a ).to eq([
+				{ "a.name" => "Adam", "b.name" => "Karissa", "f.since" => 2020 },
+				{ "a.name" => "Adam", "b.name" => "Zhang", "f.since" => 2020 },
+				{ "a.name" => "Karissa", "b.name" => "Zhang", "f.since" => 2021 },
+				{ "a.name" => "Zhang", "b.name" => "Noura", "f.since" => 2022 }
+			])
+
+			result.finish
+		end
+
+
+		it "can iterate over result sets" do
+			result = described_class.from_query( connection, <<~END_QUERY )
+				return 1;
+				return 2;
+				return 3;
+			END_QUERY
+
+			rval = result.each_set.flat_map do |subset|
+				subset.each.to_a
+			end
+
+			expect( rval ).to eq([
+				{ "1" => 1 },
+				{ "2" => 2 },
+				{ "3" => 3 },
+			])
+
+			result.finish
+		end
+
+
+		it "also finishes successive results if they've been fetched when the first one is finished" do
+			result = described_class.from_query( connection, <<~END_QUERY )
+				return 1;
+				return 2;
+				return 3;
+			END_QUERY
+
+			second_result = result.next_set
+
+			result.finish
+
+			expect( second_result ).to be_finished
+		end
+
+
+		it "errors if it's used after being finished" do
+			result = described_class.from_query( connection, "return 1;" )
+			result.finish
+
+			expect( result ).to be_finished
+
+			expect {
+				result.get_next_values
+			}.to raise_error( Kuzu::FinishedError )
+		end
+
+	end
+
+
+	describe "prepared statement constructor" do
+
+		before( :each ) do
+			setup_demo_db()
+		end
+
+
+		it "can be created via a prepared statement" do
+			statement = Kuzu::PreparedStatement.new( connection, <<~END_OF_QUERY )
+				MATCH (u:User)
+			    WHERE u.age > $min_age and u.age < $max_age
+			    RETURN u.name
+			END_OF_QUERY
+			statement.bind( min_age: 32, max_age: 46 )
+
+			result = described_class.from_prepared_statement( statement )
+
+			expect( result ).to be_a( described_class )
+			expect( result ).to be_success
+
+			result.finish
+		end
+
+
+		it "is automatically finished if constructed with a block" do
+			statement = Kuzu::PreparedStatement.new( connection, <<~END_OF_QUERY )
+				MATCH (u:User)
+			    WHERE u.age > $min_age and u.age < $max_age
+			    RETURN u.name
+			END_OF_QUERY
+			statement.bind( min_age: 32, max_age: 46 )
+
+			block_result = nil
+			rval = described_class.from_prepared_statement( statement ) do |result|
+				block_result = result
+				expect( result ).to be_a( described_class )
+				expect( result ).to be_success
+
+				result.first['u.name']
+			end
+
+			expect( block_result ).to be_finished
+			expect( rval ).to eq( "Karissa" )
+		end
+
+	end
+
+
+end

data/spec/kuzu/types_spec.rb

@@ -0,0 +1,254 @@
+# -*- ruby -*-
+
+require_relative '../spec_helper'
+
+require 'kuzu'
+
+
+RSpec.describe( "data types" ) do
+
+	let( :db ) { Kuzu.database }
+	let( :connection ) { db.connect }
+
+
+	#
+	# Specs
+	#
+
+	it "converts TIMESTAMP values to Time objects" do
+		result = connection.query( %{RETURN timestamp("1970-01-01 00:00:00.004666-10") as x;} )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+
+		value = result.first
+		expect( value ).to include( 'x' )
+
+		x = value['x']
+		expect( x ).to be_a( Time )
+		expect( x.year ).to eq( 1970 )
+		expect( x.month ).to eq( 1 )
+		expect( x.day ).to eq( 1 )
+
+		result.finish
+end
+
+
+	it "converts STRUCT values to OpenStructs" do
+		result = connection.query( "RETURN {first: 'Adam', last: 'Smith'} AS record;" )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		Kuzu.logger.debug "Result is: %p" % [ result ]
+
+		value = result.first
+		expect( value ).to include( 'record' )
+
+		record = value['record']
+		expect( record ).to be_a( OpenStruct )
+		expect( record.first ).to eq( "Adam" )
+		expect( record.first.encoding ).to eq( Encoding::UTF_8 )
+		expect( record.last ).to eq( "Smith" )
+		expect( record.last.encoding ).to eq( Encoding::UTF_8 )
+
+		result.finish
+	end
+
+
+	it "converts MAP values to Hashes" do
+		result = connection.query( "RETURN map([1, 2], ['a', 'b']) AS m;" )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		Kuzu.logger.debug "Result is: %p" % [ result ]
+
+		value = result.first
+		expect( value ).to include( 'm' )
+
+		record = value['m']
+		expect( record ).to be_a( Hash )
+		expect( record ).to eq({ 1 => 'a', 2 => 'b' })
+
+		result.finish
+	end
+
+
+	it "converts LIST values to Arrays" do
+		result = connection.query( 'RETURN ["Alice", "Bob"] AS l;' )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		Kuzu.logger.debug "Result is: %p" % [ result ]
+
+		value = result.first
+		expect( value ).to include( 'l' )
+
+		record = value['l']
+		expect( record ).to be_an( Array )
+		expect( record ).to eq( ['Alice', 'Bob'] )
+
+		result.finish
+	end
+
+
+	it "converts ARRAY values to Arrays" do
+		result = connection.query( "RETURN CAST([3,4,12,11], 'INT64[4]') as a;" )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		Kuzu.logger.debug "Result is: %p" % [ result ]
+
+		value = result.first
+		expect( value ).to include( 'a' )
+
+		record = value['a']
+		expect( record ).to be_an( Array )
+		expect( record ).to eq( [3, 4, 12, 11] )
+
+		result.finish
+	end
+
+
+	it "converts ARRAYs of LIST values correctly" do
+		result = connection.query( "RETURN CAST([[5,2,1],[2,3],[15,64,74]], 'INT64[][3]') as a;" )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		Kuzu.logger.debug "Result is: %p" % [ result ]
+
+		value = result.first
+		expect( value ).to include( 'a' )
+
+		record = value['a']
+		expect( record ).to be_an( Array )
+		expect( record ).to eq( [ [5, 2, 1], [2, 3], [15, 64, 74] ] )
+
+		result.finish
+	end
+
+
+	it "converts NODE values to Kuzu::Node objects" do
+		connection.run( <<~END_OF_SCHEMA )
+			CREATE NODE TABLE Person(id INT64, name STRING, age INT64, PRIMARY KEY(id));
+			COPY Person FROM 'spec/data/test/Person.csv';
+		END_OF_SCHEMA
+		result = connection.query( "MATCH (a:Person) RETURN a;" )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		expect( result.num_tuples ).to eq( 120 )
+
+		result.each do |value|
+			expect( value ).to include( 'a' )
+
+			node = value['a']
+			expect( node ).to be_a( Kuzu::Node )
+
+			expect( node.properties.keys ).to contain_exactly( :id, :name, :age )
+		end
+
+		result.finish
+	end
+
+
+	it "converts REL values to Kuzu::Rel objects" do
+		connection.run( <<~END_OF_SCHEMA )
+			CREATE NODE TABLE Person(id INT64, name STRING, age INT64, PRIMARY KEY(id));
+			CREATE REL TABLE Follows (from Person to Person, since INT64);
+			COPY Person FROM 'spec/data/test/Person.csv';
+			COPY Follows FROM 'spec/data/test/Follows.csv';
+		END_OF_SCHEMA
+		result = connection.query( "MATCH (a:Person)-[r:Follows]->(b:Person) RETURN r;" )
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+		expect( result.num_tuples ).to eq( 5 )
+
+		result.each do |value|
+			expect( value ).to include( 'r' )
+
+			rel = value['r']
+			expect( rel ).to be_a( Kuzu::Rel )
+
+			expect( rel.src_id ).to_not be_nil
+			expect( rel.dst_id ).to_not be_nil
+
+			expect( rel.properties.keys ).to contain_exactly( :since )
+		end
+
+		result.finish
+	end
+
+
+	it "converts RECURSIVE_REL values to Kuzu::RecursiveRel objects" do
+		connection.run( <<~END_OF_SCHEMA )
+			CREATE NODE TABLE Person(id INT64, name STRING, age INT64, PRIMARY KEY(id));
+			CREATE REL TABLE Follows (from Person to Person, since INT64);
+			COPY Person FROM 'spec/data/test/Person.csv';
+			COPY Follows FROM 'spec/data/test/Follows.csv';
+		END_OF_SCHEMA
+		result = connection.query( <<~END_OF_QUERY )
+			MATCH p = (a:Person)-[:Follows]->(b:Person)
+			WHERE a.name = 'Jake Kling' AND b.name = 'Joaquin Schamberger'
+			RETURN p;
+		END_OF_QUERY
+
+		expect( result ).to be_a( Kuzu::Result )
+		expect( result ).to be_success
+
+		result.each do |value|
+			expect( value ).to include( 'p' )
+
+			rel = value['p']
+			expect( rel ).to be_a( Kuzu::RecursiveRel )
+
+			expect( rel.nodes ).to be_an( Array ).and have_attributes( length: 2 )
+			expect( rel.nodes[0] ).to be_a( Kuzu::Node )
+			expect( rel.nodes[0][:name] ).to eq( 'Jake Kling' )
+			expect( rel.nodes[1] ).to be_a( Kuzu::Node )
+			expect( rel.nodes[1][:name] ).to eq( 'Joaquin Schamberger' )
+
+			expect( rel.rels ).to be_an( Array ).and have_attributes( length: 1 )
+			expect( rel.rels[0][:since] ).to eq( 2012 )
+		end
+
+		result.finish
+	end
+
+
+	it "converts UNIONs to something"
+
+
+	it "converts between nil and NULL" do
+		stmt = connection.prepare( "RETURN $the_value AS value;" )
+		result = stmt.execute( the_value: nil )
+
+		expect( result.first ).to eq( {'value' => nil} )
+
+		result.finish
+	end
+
+
+	it "converts UUIDs to Strings" do
+		result = connection.query( "RETURN UUID('A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11') as u;" )
+		uuid = result.first['u']
+
+		expect( uuid ).to be_a( String )
+		expect( uuid ).to eq( 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11' )
+
+		result.finish
+	end
+
+
+	it "converts DECIMAL types to Float objects" do
+		result = connection.query( %{RETURN CAST(127.3, "DECIMAL(5, 2)") AS d;} )
+		rval = result.first['d']
+
+		expect( rval ).to be_a( Float )
+		expect( rval ).to eq( 127.3 )
+
+		result.finish
+	end
+
+
+end

data/spec/kuzu_spec.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby -S rspec
+
+require_relative 'spec_helper'
+require 'kuzu'
+
+
+RSpec.describe( Kuzu ) do
+
+	let( :spec_tmpdir ) do
+		tmpfile_pathname()
+	end
+
+
+	it "should have a VERSION constant" do
+		expect( subject.const_get('VERSION') ).to_not be_empty
+	end
+
+
+	it "knows what version of Kuzu it's linked with" do
+		expect( described_class.kuzu_version ).to match( /\A\d+\.\d+\.\d+/ )
+	end
+
+
+	it "knows what version of the storage scheme it's using" do
+		result = described_class.storage_version
+
+		expect( result ).to be_an( Integer )
+		expect( result ).to be > 0
+	end
+
+
+	it "can construct an in-memory database with reasonable defaults" do
+		expect( described_class.database ).to be_a( Kuzu::Database )
+	end
+
+
+	it "can construct an in-memory database with a nil path" do
+		expect( described_class.database(nil) ).to be_a( Kuzu::Database )
+	end
+
+
+	it "can construct an in-memory database explicitly" do
+		expect( described_class.database(:memory) ).to be_a( Kuzu::Database )
+	end
+
+
+	it "can construct a on-disk database with reasonable defaults" do
+		filename = spec_tmpdir + 'spec_db'
+		result = described_class.database( filename )
+
+		expect( result ).to be_a( Kuzu::Database )
+		expect( filename ).to be_a_directory
+	end
+
+end