duckdb 1.1.3.0 → 1.2.0.0

data/lib/duckdb/appender.rb

@@ -13,15 +13,216 @@ module DuckDB
   #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
   #   appender = con.appender('users')
   #   appender.append_row(1, 'Alice')
-  #
   class Appender
     include DuckDB::Converter
 
+    # :stopdoc:
     RANGE_INT16 = -32_768..32_767
     RANGE_INT32 = -2_147_483_648..2_147_483_647
     RANGE_INT64 = -9_223_372_036_854_775_808..9_223_372_036_854_775_807
+    private_constant :RANGE_INT16, :RANGE_INT32, :RANGE_INT64
+    # :startdoc:
+
+    # :call-seq:
+    #   appender.begin_row -> self
+    # A nop method, provided for backwards compatibility reasons.
+    # Does nothing. Only `end_row` is required.
+    def begin_row
+      self
+    end
+
+    # call-seq:
+    #   appender.end_row -> self
+    #
+    # Finish the current row of appends. After end_row is called, the next row can be appended.
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_varchar('Alice')
+    #     .end_row
+    def end_row
+      return self if _end_row
+
+      raise_appender_error('failed to end_row')
+    end
+
+    # :call-seq:
+    #   appender.flush -> self
+    #
+    # Flushes the appender to the table, forcing the cache of the appender to be cleared.
+    # If flushing the data triggers a constraint violation or any other error, then all
+    # data is invalidated, and this method raises DuckDB::Error.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_varchar('Alice')
+    #     .end_row
+    #     .flush
+    def flush
+      return self if _flush
+
+      raise_appender_error('failed to flush')
+    end
+
+    # :call-seq:
+    #   appender.close -> self
+    #
+    # Closes the appender by flushing all intermediate states and closing it for further appends.
+    # If flushing the data triggers a constraint violation or any other error, then all data is
+    # invalidated, and this method raises DuckDB::Error.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_varchar('Alice')
+    #     .end_row
+    #     .close
+    def close
+      return self if _close
+
+      raise_appender_error('failed to close')
+    end
+
+    # call-seq:
+    #   appender.append_bool(val) -> self
+    #
+    # Appends a boolean value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, active BOOLEAN)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_bool(true)
+    #     .end_row
+    #     .flush
+    def append_bool(value)
+      return self if _append_bool(value)
+
+      raise_appender_error('failed to append_bool')
+    end
+
+    # call-seq:
+    #   appender.append_int8(val) -> self
+    #
+    # Appends an int8(TINYINT) value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age TINYINT)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_int8(20)
+    #     .end_row
+    #     .flush
+    #
+    def append_int8(value)
+      return self if _append_int8(value)
+
+      raise_appender_error('failed to append_int8')
+    end
 
+    # call-seq:
+    #   appender.append_int16(val) -> self
     #
+    # Appends an int16(SMALLINT) value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age SMALLINT)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_int16(20)
+    #     .end_row
+    #     .flush
+    def append_int16(value)
+      return self if _append_int16(value)
+
+      raise_appender_error('failed to append_int16')
+    end
+
+    # call-seq:
+    #   appender.append_int32(val) -> self
+    #
+    # Appends an int32(INTEGER) value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age INTEGER)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_int32(20)
+    #     .end_row
+    #     .flush
+    def append_int32(value)
+      return self if _append_int32(value)
+
+      raise_appender_error('failed to append_int32')
+    end
+
+    # call-seq:
+    #   appender.append_int64(val) -> self
+    #
+    # Appends an int64(BIGINT) value to the current row in the appender.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE users (id INTEGER, age BIGINT)')
+    #   appender = con.appender('users')
+    #   appender
+    #     .append_int32(1)
+    #     .append_int64(20)
+    #     .end_row
+    #     .flush
+    def append_int64(value)
+      return self if _append_int64(value)
+
+      raise_appender_error('failed to append_int64')
+    end
+
+    # call-seq:
+    #  appender.append_uint8(val) -> self
+    #
+    # Appends an uint8 value to the current row in the appender.
+    #
+    #  require 'duckdb'
+    #  db = DuckDB::Database.open
+    #  con = db.connect
+    #  con.query('CREATE TABLE users (id INTEGER, age UTINYINT)')
+    #  appender = con.appender('users')
+    #  appender
+    #    .append_int32(1)
+    #    .append_uint8(20)
+    #    .end_row
+    #    .flush
+    def append_uint8(value)
+      return self if _append_uint8(value)
+
+      raise_appender_error('failed to append_uint8')
+    end
+
     # appends huge int value.
     #
     #   require 'duckdb'
@@ -30,16 +231,13 @@ module DuckDB
     #   con.query('CREATE TABLE numbers (num HUGEINT)')
     #   appender = con.appender('numbers')
     #   appender
-    #     .begin_row
     #     .append_hugeint(-170_141_183_460_469_231_731_687_303_715_884_105_727)
     #     .end_row
-    #
     def append_hugeint(value)
       lower, upper = integer_to_hugeint(value)
       _append_hugeint(lower, upper)
     end
 
-    #
     # appends unsigned huge int value.
     #
     #   require 'duckdb'
@@ -48,16 +246,13 @@ module DuckDB
     #   con.query('CREATE TABLE numbers (num UHUGEINT)')
     #   appender = con.appender('numbers')
     #   appender
-    #     .begin_row
     #     .append_hugeint(340_282_366_920_938_463_463_374_607_431_768_211_455)
     #     .end_row
-    #
     def append_uhugeint(value)
       lower, upper = integer_to_hugeint(value)
       _append_uhugeint(lower, upper)
     end
 
-    #
     # appends date value.
     #
     #   require 'duckdb'
@@ -65,21 +260,18 @@ module DuckDB
     #   con = db.connect
     #   con.query('CREATE TABLE dates (date_value DATE)')
     #   appender = con.appender('dates')
-    #   appender.begin_row
     #   appender.append_date(Date.today)
     #   # or
     #   # appender.append_date(Time.now)
     #   # appender.append_date('2021-10-10')
     #   appender.end_row
     #   appender.flush
-    #
     def append_date(value)
-      date = to_date(value)
+      date = _parse_date(value)
 
       _append_date(date.year, date.month, date.day)
     end
 
-    #
     # appends time value.
     #
     #   require 'duckdb'
@@ -87,20 +279,17 @@ module DuckDB
     #   con = db.connect
     #   con.query('CREATE TABLE times (time_value TIME)')
     #   appender = con.appender('times')
-    #   appender.begin_row
     #   appender.append_time(Time.now)
     #   # or
     #   # appender.append_time('01:01:01')
     #   appender.end_row
     #   appender.flush
-    #
     def append_time(value)
       time = _parse_time(value)
 
       _append_time(time.hour, time.min, time.sec, time.usec)
     end
 
-    #
     # appends timestamp value.
     #
     #   require 'duckdb'
@@ -108,21 +297,18 @@ module DuckDB
     #   con = db.connect
     #   con.query('CREATE TABLE timestamps (timestamp_value TIMESTAMP)')
     #   appender = con.appender('timestamps')
-    #   appender.begin_row
     #   appender.append_time(Time.now)
     #   # or
     #   # appender.append_time(Date.today)
     #   # appender.append_time('2021-08-01 01:01:01')
     #   appender.end_row
     #   appender.flush
-    #
     def append_timestamp(value)
       time = to_time(value)
 
       _append_timestamp(time.year, time.month, time.day, time.hour, time.min, time.sec, time.nsec / 1000)
     end
 
-    #
     # appends interval.
     # The argument must be ISO8601 duration format.
     # WARNING: This method is expremental.
@@ -133,17 +319,14 @@ module DuckDB
     #   con.query('CREATE TABLE intervals (interval_value INTERVAL)')
     #   appender = con.appender('intervals')
     #   appender
-    #     .begin_row
     #     .append_interval('P1Y2D') # => append 1 year 2 days interval.
     #     .end_row
     #     .flush
-    #
     def append_interval(value)
       value = Interval.to_interval(value)
       _append_interval(value.interval_months, value.interval_days, value.interval_micros)
     end
 
-    #
     # appends value.
     #
     #   require 'duckdb'
@@ -151,11 +334,9 @@ module DuckDB
     #   con = db.connect
     #   con.query('CREATE TABLE users (id INTEGER, name VARCHAR)')
     #   appender = con.appender('users')
-    #   appender.begin_row
     #   appender.append(1)
     #   appender.append('Alice')
     #   appender.end_row
-    #
     def append(value)
       case value
       when NilClass
@@ -188,20 +369,16 @@ module DuckDB
       end
     end
 
-    #
     # append a row.
     #
     #   appender.append_row(1, 'Alice')
     #
     # is same as:
     #
-    #   appender.begin_row
-    #   appender.append(1)
+    #   appender.append(2)
     #   appender.append('Alice')
     #   appender.end_row
-    #
     def append_row(*args)
-      begin_row
       args.each do |arg|
         append(arg)
       end
@@ -210,35 +387,21 @@ module DuckDB
 
     private
 
-    def blob?(value)
-      value.instance_of?(DuckDB::Blob) || value.encoding == Encoding::BINARY
+    def raise_appender_error(default_message) # :nodoc:
+      message = error_message
+      raise DuckDB::Error, message || default_message
     end
 
-    def to_date(value)
-      case value
-      when Date, Time
-        value
-      else
-        begin
-          Date.parse(value)
-        rescue StandardError
-          raise(ArgumentError, "Cannot parse argument `#{value}` to Date.")
-        end
-      end
+    def blob?(value) # :nodoc:
+      value.instance_of?(DuckDB::Blob) || value.encoding == Encoding::BINARY
     end
 
-    def to_time(value)
+    def to_time(value) # :nodoc:
       case value
-      when Time
-        value
       when Date
         value.to_time
       else
-        begin
-          Time.parse(value)
-        rescue StandardError
-          raise(ArgumentError, "Cannot parse argument `#{value}` to Time or Date.")
-        end
+        _parse_time(value)
       end
     end
   end

data/lib/duckdb/column.rb

@@ -2,7 +2,6 @@
 
 module DuckDB
   class Column
-    #
     # returns column type symbol
     # `:unknown` means that the column type is unknown/unsupported by ruby-duckdb.
     # `:invalid` means that the column type is invalid in duckdb.
@@ -15,7 +14,6 @@ module DuckDB
     #   users = con.query('SELECT * FROM users')
     #   columns = users.columns
     #   columns.first.type #=> :integer
-    #
     def type
       type_id = _type
       DuckDB::Converter::IntToSym.type_to_sym(type_id)

data/lib/duckdb/connection.rb

@@ -8,7 +8,6 @@ module DuckDB
   #   con = db.connect
   #   con.query(sql)
   class Connection
-    #
     # executes sql with args.
     # The first argument sql must be SQL string.
     # The rest arguments are parameters of SQL string.
@@ -24,7 +23,6 @@ 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, **kwargs)
       return query_multi_sql(sql) if args.empty? && kwargs.empty?
 
@@ -39,13 +37,13 @@ module DuckDB
       result = nil
       stmts.each do |stmt|
         result = stmt.execute
+        stmt.destroy
       end
       result
     ensure
       stmts&.destroy
     end
 
-    #
     # executes sql with args asynchronously.
     # The first argument sql must be SQL string.
     # The rest arguments are parameters of SQL string.
@@ -60,7 +58,6 @@ module DuckDB
     #   pending_result.execute_task while pending_result.state == :not_ready
     #   result = pending_result.execute_pending
     #   result.each.first
-    #
     def async_query(sql, *args, **kwargs)
       prepare(sql) do |stmt|
         stmt.bind_args(*args, **kwargs)
@@ -68,7 +65,6 @@ module DuckDB
       end
     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.
@@ -84,7 +80,6 @@ module DuckDB
     #   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)
       prepare(sql) do |stmt|
         stmt.bind_args(*args, **kwargs)
@@ -92,10 +87,8 @@ module DuckDB
       end
     end
 
-    #
     # connects DuckDB database
     # The first argument is DuckDB::Database object
-    #
     def connect(db)
       conn = _connect(db)
       return conn unless block_given?
@@ -107,7 +100,6 @@ module DuckDB
       end
     end
 
-    #
     # returns PreparedStatement object.
     # The first argument is SQL string.
     # If block is given, the block is executed with PreparedStatement object
@@ -127,17 +119,14 @@ module DuckDB
     #              stmt.bind_args(name: 'Dave', email: 'dave@example.com')
     #              stmt.execute
     #            end
-    #
     def prepared_statement(str, &)
       return PreparedStatement.new(self, str) unless block_given?
 
       PreparedStatement.prepare(self, str, &)
     end
 
-    #
     # returns Appender object.
     # The first argument is table name
-    #
     def appender(table)
       appender = create_appender(table)
 

data/lib/duckdb/database.rb

@@ -20,13 +20,11 @@ module DuckDB
   #   result.each do |row|
   #     p row
   #   end
-  #
   class Database
     private_class_method :_open
     private_class_method :_open_ext
 
     class << self
-      ##
       # Opens database.
       # The first argument is DuckDB database file path to open.
       # If there is no argument, the method opens DuckDB database in memory.
@@ -40,7 +38,6 @@ module DuckDB
       #     con = db.connect
       #     con.query('CREATE TABLE users (id INTEGER, name VARCHAR(30))')
       #   end
-      #
       def open(dbpath = nil, config = nil)
         db = _db_open(dbpath, config)
         return db unless block_given?
@@ -54,7 +51,7 @@ module DuckDB
 
       private
 
-      def _db_open(dbpath, config)
+      def _db_open(dbpath, config) # :nodoc:
         if config
           _open_ext(dbpath, config)
         else
@@ -63,7 +60,6 @@ module DuckDB
       end
     end
 
-    ##
     # connects database.
     #
     # The method yields block and disconnects the database if block given
@@ -75,7 +71,6 @@ module DuckDB
     #   db.connect do |con|
     #     con.query('CREATE TABLE users (id INTEGER, name VARCHAR(30))')
     #   end
-    #
     def connect
       conn = _connect
       return conn unless block_given?

data/lib/duckdb/interval.rb

@@ -24,11 +24,11 @@ module DuckDB
   #   con.query('CREATE TABLE intervals (interval_value INTERVAL)')
   #   appender = con.appender('intervals')
   #   appender
-  #     .begin_row
   #     .append_interval(interval)
   #     .end_row
   #     .flush
   class Interval
+    # :stopdoc:
     ISO8601_REGEXP = Regexp.compile(
       '(?<negativ>-{0,1})P
       (?<year>-{0,1}\d+Y){0,1}
@@ -40,6 +40,8 @@ module DuckDB
       ((?<sec>-{0,1}\d+)\.{0,1}(?<usec>\d*)S){0,1}',
       Regexp::EXTENDED
     )
+    private_constant :ISO8601_REGEXP
+    # :startdoc:
 
     class << self
       # parses the ISO8601 format string and return the Interval object.
@@ -93,7 +95,7 @@ module DuckDB
 
       private
 
-      def matched_to_i(matched)
+      def matched_to_i(matched) # :nodoc:
         sign = to_sign(matched)
         sec = to_sec(matched)
         usec = to_usec(matched)
@@ -104,35 +106,35 @@ module DuckDB
         sign.positive? ? value : value.map { |v| v * sign }
       end
 
-      def to_sign(matched)
+      def to_sign(matched) # :nodoc:
         matched[:negativ] == '-' ? -1 : 1
       end
 
-      def to_year(matched)
+      def to_year(matched) # :nodoc:
         matched[:year].to_i
       end
 
-      def to_month(matched)
+      def to_month(matched) # :nodoc:
         matched[:month].to_i
       end
 
-      def to_day(matched)
+      def to_day(matched) # :nodoc:
         matched[:day].to_i
       end
 
-      def to_hour(matched)
+      def to_hour(matched) # :nodoc:
         matched[:hour].to_i
       end
 
-      def to_min(matched)
+      def to_min(matched) # :nodoc:
         matched[:min].to_i
       end
 
-      def to_sec(matched)
+      def to_sec(matched) # :nodoc:
         matched[:sec].to_i
       end
 
-      def to_usec(matched)
+      def to_usec(matched) # :nodoc:
         matched[:usec].to_s.ljust(6, '0')[0, 6].to_i
       end
     end

data/lib/duckdb/library_version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module DuckDB
+  # represents the version of the DuckDB library.
+  # If DuckDB.library_version is v0.2.0, then DuckDB::LIBRARY_VERSION is 0.2.0.
   LIBRARY_VERSION = library_version[1..]
 end

data/lib/duckdb/logical_type.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DuckDB
+  class LogicalType
+    # returns logical type's type symbol
+    # `:unknown` means that the logical type's type is unknown/unsupported by ruby-duckdb.
+    # `:invalid` means that the logical type's type is invalid in duckdb.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE climates (id INTEGER, temperature DECIMAIL)')
+    #
+    #   users = con.query('SELECT * FROM climates')
+    #   columns = users.columns
+    #   columns.second.logical_type.type #=> :decimal
+    def type
+      type_id = _type
+      DuckDB::Converter::IntToSym.type_to_sym(type_id)
+    end
+  end
+end

data/lib/duckdb/pending_result.rb

@@ -19,7 +19,7 @@ module DuckDB
   #   end
   #   result = pending_result.execute_pending
   class PendingResult
-    STATES = %i[ready not_ready error no_tasks].freeze
+    STATES = %i[ready not_ready error no_tasks].freeze # :nodoc:
 
     # returns the state of the pending result.
     # the result can be :ready, :not_ready, :error, :no_tasks.