duckdb 0.9.1.1 → 0.9.2

data/lib/duckdb/connection.rb

@@ -25,19 +25,60 @@ module DuckDB
     #   sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
     #   dave = con.query(sql, name: 'Dave', email: 'dave@example.com')
     #
-    def query(sql, *args, **hash)
-      return query_sql(sql) if args.empty? && hash.empty?
+    def query(sql, *args, **kwargs)
+      return query_sql(sql) if args.empty? && kwargs.empty?
 
       stmt = PreparedStatement.new(self, sql)
-      args.each.with_index(1) do |arg, i|
-        stmt.bind(i, arg)
-      end
-      hash.each do |key, value|
-        stmt.bind(key, value)
-      end
+      stmt.bind_args(*args, **kwargs)
       stmt.execute
     end
 
+    #
+    # executes sql with args asynchronously.
+    # The first argument sql must be SQL string.
+    # The rest arguments are parameters of SQL string.
+    # This method returns DuckDB::PendingResult object.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open('duckdb_file')
+    #   con = db.connect
+    #
+    #   sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
+    #   pending_result = con.async_query(sql, name: 'Dave', email: 'dave@example.com')
+    #   pending_result.execute_task while pending_result.state == :not_ready
+    #   result = pending_result.execute_pending
+    #   result.each.first
+    #
+    def async_query(sql, *args, **kwargs)
+      stmt = PreparedStatement.new(self, sql)
+      stmt.bind_args(*args, **kwargs)
+      stmt.pending_prepared
+    end
+
+    #
+    # executes sql with args asynchronously and provides streaming result.
+    # The first argument sql must be SQL string.
+    # The rest arguments are parameters of SQL string.
+    # This method returns DuckDB::PendingResult object.
+    #
+    #   require 'duckdb'
+    #   DuckDB::Result.use_chunk_each = true # must be true
+    #   db = DuckDB::Database.open('duckdb_file')
+    #   con = db.connect
+    #
+    #   sql = 'SELECT * FROM users WHERE name = $name AND email = $email'
+    #   pending_result = con.async_query_stream(sql, name: 'Dave', email: 'dave@example.com')
+    #
+    #   pending_result.execute_task while pending_result.state == :not_ready
+    #   result = pending_result.execute_pending
+    #   result.each.first
+    #
+    def async_query_stream(sql, *args, **kwargs)
+      stmt = PreparedStatement.new(self, sql)
+      stmt.bind_args(*args, **kwargs)
+      stmt.pending_prepared_stream
+    end
+
     #
     # connects DuckDB database
     # The first argument is DuckDB::Database object
@@ -83,6 +124,7 @@ module DuckDB
     end
 
     alias execute query
+    alias async_execute async_query
     alias open connect
     alias close disconnect
   end

data/lib/duckdb/converter.rb

@@ -42,6 +42,32 @@ module DuckDB
       "#{str[0, 8]}-#{str[8, 4]}-#{str[12, 4]}-#{str[16, 4]}-#{str[20, 12]}"
     end
 
+    def _parse_date(value)
+      case value
+      when Date, Time
+        value
+      else
+        begin
+          Date.parse(value)
+        rescue StandardError => e
+          raise(ArgumentError, "Cannot parse `#{value.inspect}` to Date object. #{e.message}")
+        end
+      end
+    end
+
+    def _parse_time(value)
+      case value
+      when Time
+        value
+      else
+        begin
+          Time.parse(value)
+        rescue StandardError => e
+          raise(ArgumentError, "Cannot parse `#{value.inspect}` to Time object. #{e.message}")
+        end
+      end
+    end
+
     private
 
     def integer_to_hugeint(value)
@@ -51,7 +77,7 @@ module DuckDB
         lower = value - (upper << HALF_HUGEINT_BIT)
         [lower, upper]
       else
-        raise(ArgumentError, "The argument `#{value}` must be Integer.")
+        raise(ArgumentError, "The argument `#{value.inspect}` must be Integer.")
       end
     end
   end

data/lib/duckdb/prepared_statement.rb

@@ -24,21 +24,49 @@ module DuckDB
       PendingResult.new(self)
     end
 
+    def pending_prepared_stream
+      raise DuckDB::Error, 'DuckDB::Result.use_chunk_each must be true.' unless DuckDB::Result.use_chunk_each?
+
+      PendingResult.new(self, true)
+    end
+
+    # binds all parameters with SQL prepared statement.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open('duckdb_database')
+    #   con = db.connect
+    #   sql ='SELECT name FROM users WHERE id = ?'
+    #   # or
+    #   # sql ='SELECT name FROM users WHERE id = $id'
+    #   stmt = PreparedStatement.new(con, sql)
+    #   stmt.bind_args([1])
+    #   # or
+    #   # stmt.bind_args(id: 1)
+    def bind_args(*args, **kwargs)
+      args.each.with_index(1) do |arg, i|
+        bind(i, arg)
+      end
+      kwargs.each do |key, value|
+        bind(key, value)
+      end
+    end
+
     # binds i-th parameter with SQL prepared statement.
     # The first argument is index of parameter.
     # The index of first parameter is 1 not 0.
     # The second argument value is to expected Integer value.
     # This method uses bind_varchar internally.
+    #
     #   require 'duckdb'
     #   db = DuckDB::Database.open('duckdb_database')
     #   con = db.connect
     #   sql ='SELECT name FROM users WHERE bigint_col = ?'
     #   stmt = PreparedStatement.new(con, sql)
     #   stmt.bind_hugeint(1, 1_234_567_890_123_456_789_012_345)
-    def bind_hugeint(i, value)
+    def bind_hugeint(index, value)
       case value
       when Integer
-        bind_varchar(i, value.to_s)
+        bind_varchar(index, value.to_s)
       else
         raise(ArgumentError, "2nd argument `#{value}` must be Integer.")
       end
@@ -49,6 +77,7 @@ module DuckDB
     # The index of first parameter is 1 not 0.
     # The second argument value must be Integer value.
     # This method uses duckdb_bind_hugeint internally.
+    #
     #   require 'duckdb'
     #   db = DuckDB::Database.open('duckdb_database')
     #   con = db.connect
@@ -73,19 +102,10 @@ module DuckDB
     #   stmt.bind(1, Date.today)
     #   #  or you can specify date string.
     #   # stmt.bind(1, '2021-02-23')
-    def bind_date(i, value)
-      case value
-      when Date, Time
-        date = value
-      else
-        begin
-          date = Date.parse(value)
-        rescue => e
-          raise(ArgumentError, "Cannot parse argument value to date. #{e.message}")
-        end
-      end
+    def bind_date(index, value)
+      date = _parse_date(value)
 
-      _bind_date(i, date.year, date.month, date.day)
+      _bind_date(index, date.year, date.month, date.day)
     end
 
     # binds i-th parameter with SQL prepared statement.
@@ -101,19 +121,10 @@ module DuckDB
     #   stmt.bind(1, Time.now)
     #   #  or you can specify time string.
     #   # stmt.bind(1, '07:39:45')
-    def bind_time(i, value)
-      case value
-      when Time
-        time = value
-      else
-        begin
-          time = Time.parse(value)
-        rescue => e
-          raise(ArgumentError, "Cannot parse argument value to time. #{e.message}")
-        end
-      end
+    def bind_time(index, value)
+      time = _parse_time(value)
 
-      _bind_time(i, time.hour, time.min, time.sec, time.usec)
+      _bind_time(index, time.hour, time.min, time.sec, time.usec)
     end
 
     # binds i-th parameter with SQL prepared statement.
@@ -129,19 +140,10 @@ module DuckDB
     #   stmt.bind(1, Time.now)
     #   #  or you can specify timestamp string.
     #   # stmt.bind(1, '2022-02-23 07:39:45')
-    def bind_timestamp(i, value)
-      case value
-      when Time
-        time = value
-      else
-        begin
-          time = Time.parse(value)
-        rescue => e
-          raise(ArgumentError, "Cannot parse argument value to time. #{e.message}")
-        end
-      end
+    def bind_timestamp(index, value)
+      time = _parse_time(value)
 
-      _bind_timestamp(i, time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
+      _bind_timestamp(index, time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
     end
 
     # binds i-th parameter with SQL prepared statement.
@@ -155,9 +157,9 @@ module DuckDB
     #   sql ='SELECT value FROM intervals WHERE interval = ?'
     #   stmt = PreparedStatement.new(con, sql)
     #   stmt.bind(1, 'P1Y2D')
-    def bind_interval(i, value)
+    def bind_interval(index, value)
       value = Interval.to_interval(value)
-      _bind_interval(i, value.interval_months, value.interval_days, value.interval_micros)
+      _bind_interval(index, value.interval_months, value.interval_days, value.interval_micros)
     end
 
     # binds i-th parameter with SQL prepared statement.

data/lib/duckdb/result.rb

@@ -58,9 +58,15 @@ module DuckDB
 
     def each
       if self.class.use_chunk_each?
-        return chunk_each unless block_given?
+        if streaming?
+          return _chunk_stream unless block_given?
 
-        chunk_each { |row| yield row }
+          _chunk_stream { |row| yield row }
+        else
+          return chunk_each unless block_given?
+
+          chunk_each { |row| yield row }
+        end
       else
         warn('this `each` behavior will be deprecated in the future. set `DuckDB::Result.use_chunk_each = true` to use new `each` behavior.')
         return to_enum { row_size } unless block_given?

data/lib/duckdb/version.rb

@@ -3,5 +3,5 @@
 module DuckDB
   # The version string of ruby-duckdb.
   # Currently, ruby-duckdb is NOT semantic versioning.
-  VERSION = '0.9.1.1'
+  VERSION = '0.9.2'
 end

data/sample/async_query.rb

@@ -0,0 +1,24 @@
+require 'duckdb'
+
+DuckDB::Result.use_chunk_each = true
+DuckDB::Database.open do |db|
+  db.connect do |con|
+    con.query('SET threads=1')
+    con.query('CREATE TABLE tbl as SELECT range a, mod(range, 10) b FROM range(10000)')
+    con.query('CREATE TABLE tbl2 as SELECT range a, mod(range, 10) b FROM range(10000)')
+    # con.query('SET ENABLE_PROGRESS_BAR=true')
+    # con.query('SET ENABLE_PROGRESS_BAR_PRINT=false')
+    pending_result = con.async_query('SELECT * FROM tbl where b = (SELECT min(b) FROM tbl2)')
+
+    # con.interrupt
+    while pending_result.state == :not_ready
+      pending_result.execute_task
+      print '.'
+      $stdout.flush
+      sleep 0.01
+    end
+    result = pending_result.execute_pending
+    puts
+    p result.each.first
+  end
+end

data/sample/async_query_stream.rb

@@ -0,0 +1,24 @@
+require 'duckdb'
+
+DuckDB::Result.use_chunk_each = true
+DuckDB::Database.open do |db|
+  db.connect do |con|
+    con.query('SET threads=1')
+    con.query('CREATE TABLE tbl as SELECT range a, mod(range, 10) b FROM range(10000)')
+    con.query('CREATE TABLE tbl2 as SELECT range a, mod(range, 10) b FROM range(10000)')
+    # con.query('SET ENABLE_PROGRESS_BAR=true')
+    # con.query('SET ENABLE_PROGRESS_BAR_PRINT=false')
+    pending_result = con.async_query_stream('SELECT * FROM tbl where b = (SELECT min(b) FROM tbl2)')
+
+    # con.interrupt
+    while pending_result.state == :not_ready
+      pending_result.execute_task
+      print '.'
+      $stdout.flush
+      sleep 0.01
+    end
+    result = pending_result.execute_pending
+    puts
+    p result.each.first
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duckdb
 version: !ruby/object:Gem::Version
-  version: 0.9.1.1
+  version: 0.9.2
 platform: ruby
 authors:
 - Masaki Suketa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-28 00:00:00.000000000 Z
+date: 2023-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,6 +75,7 @@ extensions:
 - ext/duckdb/extconf.rb
 extra_rdoc_files: []
 files:
+- ".gitattributes"
 - ".github/FUNDING.yml"
 - ".github/workflows/test_on_macos.yml"
 - ".github/workflows/test_on_ubuntu.yml"
@@ -88,6 +89,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- benchmark/async_query.rb
 - benchmark/converter_hugeint_ips.rb
 - benchmark/get_converter_module_ips.rb
 - benchmark/to_bigdecimal_ips.rb
@@ -138,6 +140,8 @@ files:
 - lib/duckdb/prepared_statement.rb
 - lib/duckdb/result.rb
 - lib/duckdb/version.rb
+- sample/async_query.rb
+- sample/async_query_stream.rb
 homepage: https://github.com/suketa/ruby-duckdb
 licenses:
 - MIT