duckdb 1.4.2.0 → 1.4.4.0

data/lib/duckdb/bind_info.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DuckDB
+  #
+  # The DuckDB::BindInfo encapsulates information for the bind phase of table functions.
+  #
+  # During the bind phase, you can:
+  # - Access parameters passed to the function
+  # - Define the output schema (columns)
+  # - Set performance hints (cardinality)
+  # - Report errors
+  #
+  # Example:
+  #
+  #   table_function.bind do |bind_info|
+  #     # Get parameters
+  #     limit = bind_info.get_parameter(0).to_i
+  #
+  #     # Define output schema
+  #     bind_info.add_result_column('id', DuckDB::LogicalType::BIGINT)
+  #     bind_info.add_result_column('name', DuckDB::LogicalType::VARCHAR)
+  #
+  #     # Set cardinality hint
+  #     bind_info.set_cardinality(limit, true)
+  #   end
+  #
+  class BindInfo
+    def add_result_column(name, type)
+      _add_result_column(name.to_s, DuckDB::LogicalType.resolve(type))
+    end
+  end
+end

data/lib/duckdb/casting.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DuckDB
+  module Casting
+    def cast(value, type) # rubocop:disable Metrics/MethodLength
+      type = type.type if type.is_a?(DuckDB::LogicalType)
+      case type
+      when :integer, :bigint, :hugeint
+        Integer(value)
+      when :float, :double
+        Float(value)
+      when :varchar
+        value.to_s
+      when :timestamp
+        cast_as_timestamp(value)
+      when :date
+        cast_as_date(value)
+      else
+        raise ArgumentError, "Unsupported type: #{type} for value: #{value}"
+      end
+    end
+
+    private
+
+    def cast_as_timestamp(value)
+      DuckDB::Converter._parse_time(value)
+    end
+
+    def cast_as_date(value)
+      DuckDB::Converter._parse_date(value)
+    end
+  end
+
+  extend Casting
+end

data/lib/duckdb/connection.rb

@@ -80,10 +80,10 @@ 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)
+    def async_query_stream(sql, *, **)
       warn("`#{self.class}#{__method__}` will be deprecated. Use `#{self.class}#async_query` instead.")
 
-      async_query(sql, *args, **kwargs)
+      async_query(sql, *, **)
     end
 
     # connects DuckDB database
@@ -156,8 +156,129 @@ module DuckDB
       end
     end
 
+    # Registers a scalar function with the connection.
+    #
+    # Scalar functions with Ruby callbacks require single-threaded execution.
+    #
+    # @overload register_scalar_function(scalar_function)
+    #   Register a pre-created ScalarFunction object.
+    #   @param scalar_function [DuckDB::ScalarFunction] the scalar function to register
+    #
+    # @overload register_scalar_function(name:, return_type:, **kwargs, &block)
+    #   Create and register a scalar function inline.
+    #   @param name [String, Symbol] the function name
+    #   @param return_type [DuckDB::LogicalType] the return type
+    #   @param parameter_type [DuckDB::LogicalType, nil] single parameter type
+    #   @param parameter_types [Array<DuckDB::LogicalType>, nil] multiple parameter types
+    #   @yield [*args] the function implementation
+    #
+    # @raise [DuckDB::Error] if threads setting is not 1
+    # @raise [ArgumentError] if both object and keywords/block are provided
+    # @return [void]
+    #
+    # @example Register pre-created function
+    #   con.execute('SET threads=1')
+    #   sf = DuckDB::ScalarFunction.create(
+    #     name: :triple,
+    #     return_type: DuckDB::LogicalType::INTEGER,
+    #     parameter_type: DuckDB::LogicalType::INTEGER
+    #   ) { |v| v * 3 }
+    #   con.register_scalar_function(sf)
+    #
+    # @example Register inline (single parameter)
+    #   con.execute('SET threads=1')
+    #   con.register_scalar_function(
+    #     name: :triple,
+    #     return_type: DuckDB::LogicalType::INTEGER,
+    #     parameter_type: DuckDB::LogicalType::INTEGER
+    #   ) { |v| v * 3 }
+    #
+    # @example Register inline (multiple parameters)
+    #   con.execute('SET threads=1')
+    #   con.register_scalar_function(
+    #     name: :add,
+    #     return_type: DuckDB::LogicalType::INTEGER,
+    #     parameter_types: [DuckDB::LogicalType::INTEGER, DuckDB::LogicalType::INTEGER]
+    #   ) { |a, b| a + b }
+    def register_scalar_function(scalar_function = nil, **kwargs, &)
+      # Validate: can't pass both object and inline arguments
+      if scalar_function.is_a?(ScalarFunction)
+        raise ArgumentError, 'Cannot pass both ScalarFunction object and keyword arguments' if kwargs.any?
+
+        raise ArgumentError, 'Cannot pass both ScalarFunction object and block' if block_given?
+      end
+
+      check_threads
+      sf = scalar_function || ScalarFunction.create(**kwargs, &)
+      _register_scalar_function(sf)
+    end
+
+    #
+    # Registers a table function with the database connection.
+    #
+    #   table_function = DuckDB::TableFunction.new
+    #   table_function.name = 'my_function'
+    #   table_function.bind { |bind_info| ... }
+    #   table_function.execute { |func_info, output| ... }
+    #   connection.register_table_function(table_function)
+    #
+    def register_table_function(table_function)
+      raise ArgumentError, 'table_function must be a TableFunction' unless table_function.is_a?(TableFunction)
+
+      check_threads
+      _register_table_function(table_function)
+    end
+
+    # Exposes a Ruby object as a queryable DuckDB table function via a registered adapter.
+    #
+    # Looks up a table adapter registered for the object's class via
+    # +DuckDB::TableFunction.add_table_adapter+, then uses it to create and register
+    # a table function under the given name.
+    #
+    # @param object [Object] the Ruby object to expose as a table (e.g. a CSV instance)
+    # @param name [String] the SQL name of the table function
+    # @param columns [Hash{String => DuckDB::LogicalType}, nil] optional column schema override;
+    #   if omitted, the adapter determines the columns (e.g. from headers or inference)
+    # @raise [ArgumentError] if no adapter is registered for the object's class
+    # @raise [DuckDB::Error] if threads setting is not 1
+    # @return [void]
+    #
+    # @example Expose a CSV as a table
+    #   require 'csv'
+    #   con.execute('SET threads=1')
+    #   DuckDB::TableFunction.add_table_adapter(CSV, CSVTableAdapter.new)
+    #   csv = CSV.new(File.read('data.csv'), headers: true)
+    #   con.expose_as_table(csv, 'csv_table')
+    #   con.query('SELECT * FROM csv_table()').to_a
+    #
+    # @example With explicit column types
+    #   con.expose_as_table(csv, 'csv_table', columns: {
+    #     'id'   => DuckDB::LogicalType::BIGINT,
+    #     'name' => DuckDB::LogicalType::VARCHAR
+    #   })
+    #
+    def expose_as_table(object, name, columns: nil)
+      adapter = TableFunction.table_adapter_for(object.class)
+      raise ArgumentError, "No table adapter registered for #{object.class}" if adapter.nil?
+
+      tf = adapter.call(object, name, columns:)
+      register_table_function(tf)
+    end
+
     private
 
+    def check_threads
+      result = execute("SELECT current_setting('threads')")
+      thread_count = result.first.first.to_i
+
+      return unless thread_count > 1
+
+      raise DuckDB::Error,
+            'Functions with Ruby callbacks require single-threaded execution. ' \
+            "Current threads setting: #{thread_count}. " \
+            "Execute 'SET threads=1' before registering functions."
+    end
+
     def run_appender_block(appender, &)
       return appender unless block_given?
 

data/lib/duckdb/converter.rb

@@ -28,9 +28,11 @@ module DuckDB
       Date.new(year, month, day)
     end
 
+    # rubocop:disable Metrics/ParameterLists
     def _to_time(year, month, day, hour, minute, second, microsecond)
       Time.local(year, month, day, hour, minute, second, microsecond)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     def _to_time_from_duckdb_time(hour, minute, second, microsecond)
       Time.parse(
@@ -59,46 +61,17 @@ module DuckDB
     end
 
     def _to_time_from_duckdb_time_tz(hour, min, sec, micro, timezone)
-      sign = '+'
-      if timezone.negative?
-        timezone = -timezone
-        sign = '-'
-      end
-
-      tzhour = timezone / 3600
-      tzmin = (timezone % 3600) / 60
-
-      Time.parse(
-        format(
-          '%<hour>02d:%<min>02d:%<sec>02d.%<micro>06d%<sign>s%<tzhour>02d:%<tzmin>02d',
-          hour: hour,
-          min: min,
-          sec: sec,
-          micro: micro,
-          sign: sign,
-          tzhour: tzhour,
-          tzmin: tzmin
-        )
-      )
+      tz_offset = format_timezone_offset(timezone)
+      time_str = format('%<hour>02d:%<min>02d:%<sec>02d.%<micro>06d%<tz>s',
+                        hour: hour, min: min, sec: sec, micro: micro, tz: tz_offset)
+      Time.parse(time_str)
     end
 
     def _to_time_from_duckdb_timestamp_tz(bits)
       micro = bits % 1_000_000
-      sec = (bits / 1_000_000)
-      time = EPOCH_UTC + sec
-
-      Time.parse(
-        format(
-          '%<year>04d-%<mon>02d-%<day>02d %<hour>02d:%<min>02d:%<sec>02d.%<micro>06d +0000',
-          year: time.year,
-          mon: time.month,
-          day: time.day,
-          hour: time.hour,
-          min: time.min,
-          sec: time.sec,
-          micro: micro
-        )
-      )
+      time = EPOCH_UTC + (bits / 1_000_000)
+      timestamp_str = format_timestamp_with_micro(time, micro)
+      Time.parse(timestamp_str)
     end
 
     def _to_hugeint_from_vector(lower, upper)
@@ -134,25 +107,23 @@ module DuckDB
       when Date, Time
         value
       else
-        begin
-          Date.parse(value)
-        rescue StandardError => e
-          raise(ArgumentError, "Cannot parse `#{value.inspect}` to Date object. #{e.message}")
-        end
+        Date.parse(value)
       end
+    rescue StandardError => e
+      raise(ArgumentError, "Cannot parse `#{value.inspect}` to Date object. #{e.message}")
     end
 
     def _parse_time(value)
       case value
       when Time
         value
+      when DateTime
+        value.to_time
       else
-        begin
-          Time.parse(value)
-        rescue StandardError => e
-          raise(ArgumentError, "Cannot parse `#{value.inspect}` to Time object. #{e.message}")
-        end
+        Time.parse(value)
       end
+    rescue StandardError => e
+      raise(ArgumentError, "Cannot parse `#{value.inspect}` to Time object. #{e.message}")
     end
 
     def _parse_deciaml(value)
@@ -172,6 +143,20 @@ module DuckDB
       DuckDB::QueryProgress.new(percentage, rows_processed, total_rows_to_process).freeze
     end
 
+    def format_timezone_offset(timezone)
+      sign = timezone.negative? ? '-' : '+'
+      offset = timezone.abs
+      tzhour = offset / 3600
+      tzmin = (offset % 3600) / 60
+      format('%<sign>s%<hour>02d:%<min>02d', sign: sign, hour: tzhour, min: tzmin)
+    end
+
+    def format_timestamp_with_micro(time, micro)
+      format('%<year>04d-%<mon>02d-%<day>02d %<hour>02d:%<min>02d:%<sec>02d.%<micro>06d +0000',
+             year: time.year, mon: time.month, day: time.day,
+             hour: time.hour, min: time.min, sec: time.sec, micro: micro)
+    end
+
     private
 
     def integer_to_hugeint(value)
@@ -186,7 +171,7 @@ module DuckDB
     end
 
     def decimal_to_hugeint(value)
-      integer_value = (value * (10 ** value.scale)).to_i
+      integer_value = (value * (10**value.scale)).to_i
       integer_to_hugeint(integer_value)
     rescue FloatDomainError => e
       raise(ArgumentError, "The argument `#{value.inspect}` must be converted to Integer. #{e.message}")

data/lib/duckdb/data_chunk.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module DuckDB
+  #
+  # The DuckDB::DataChunk represents a chunk of data for table function output.
+  #
+  # During table function execution, data chunks are used to return rows.
+  #
+  # Example:
+  #
+  #   done = false
+  #   table_function.init { |_init_info| done = false }
+  #
+  #   table_function.execute do |func_info, output|
+  #     if done
+  #       output.size = 0  # Signal completion
+  #     else
+  #       # High-level API
+  #       output.set_value(0, 0, 42)        # column 0, row 0, value 42
+  #       output.set_value(1, 0, 'Alice')   # column 1, row 0, value 'Alice'
+  #       output.size = 1
+  #       done = true
+  #     end
+  #   end
+  #
+  class DataChunk
+    # Most methods are defined in C extension (ext/duckdb/data_chunk.c)
+
+    #
+    # Sets a value at the specified column and row index.
+    # Type conversion is automatic based on the column's logical type.
+    #
+    # @param col_idx [Integer] Column index (0-based)
+    # @param row_idx [Integer] Row index (0-based)
+    # @param value [Object] Value to set (Integer, Float, String, Time, Date, nil)
+    # @return [Object] The value that was set
+    #
+    # @example Set integer value
+    #   output.set_value(0, 0, 42)
+    #
+    # @example Set string value
+    #   output.set_value(1, 0, 'hello')
+    #
+    # @example Set NULL value
+    #   output.set_value(0, 1, nil)
+    #
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+    def set_value(col_idx, row_idx, value)
+      vector = get_vector(col_idx)
+      logical_type = vector.logical_type
+      type_id = logical_type.type
+
+      # Handle NULL
+      if value.nil?
+        vector.set_validity(row_idx, false)
+        return value
+      end
+
+      case type_id
+      when :boolean
+        data = vector.get_data
+        MemoryHelper.write_boolean(data, row_idx, value)
+      when :tinyint
+        data = vector.get_data
+        MemoryHelper.write_tinyint(data, row_idx, value)
+      when :smallint
+        data = vector.get_data
+        MemoryHelper.write_smallint(data, row_idx, value)
+      when :integer
+        data = vector.get_data
+        MemoryHelper.write_integer(data, row_idx, value)
+      when :bigint
+        data = vector.get_data
+        MemoryHelper.write_bigint(data, row_idx, value)
+      when :utinyint
+        data = vector.get_data
+        MemoryHelper.write_utinyint(data, row_idx, value)
+      when :usmallint
+        data = vector.get_data
+        MemoryHelper.write_usmallint(data, row_idx, value)
+      when :uinteger
+        data = vector.get_data
+        MemoryHelper.write_uinteger(data, row_idx, value)
+      when :ubigint
+        data = vector.get_data
+        MemoryHelper.write_ubigint(data, row_idx, value)
+      when :float
+        data = vector.get_data
+        MemoryHelper.write_float(data, row_idx, value)
+      when :double
+        data = vector.get_data
+        MemoryHelper.write_double(data, row_idx, value)
+      when :varchar
+        vector.assign_string_element(row_idx, value.to_s)
+      when :blob
+        vector.assign_string_element_len(row_idx, value.to_s)
+      when :timestamp
+        data = vector.get_data
+        MemoryHelper.write_timestamp(data, row_idx, value)
+      when :timestamp_tz
+        data = vector.get_data
+        MemoryHelper.write_timestamp_tz(data, row_idx, value)
+      when :date
+        data = vector.get_data
+        MemoryHelper.write_date(data, row_idx, value)
+      else
+        raise ArgumentError, "Unsupported type for DataChunk#set_value: #{type_id} for value `#{value.inspect}`"
+      end
+
+      value
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+  end
+end

data/lib/duckdb/extracted_statements.rb

@@ -6,7 +6,7 @@ module DuckDB
 
     def initialize(con, sql)
       @con = con
-      super(con, sql)
+      super
     end
 
     def each

data/lib/duckdb/function_info.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DuckDB
+  #
+  # The DuckDB::FunctionInfo provides context during table function execution.
+  #
+  # It is passed to the execute callback along with the output DataChunk.
+  #
+  # Example:
+  #
+  #   table_function.execute do |func_info, output|
+  #     # Report errors during execution
+  #     func_info.set_error('Something went wrong')
+  #   end
+  #
+  # rubocop:disable Lint/EmptyClass
+  class FunctionInfo
+    # All methods are defined in C extension (ext/duckdb/function_info.c)
+  end
+  # rubocop:enable Lint/EmptyClass
+end

data/lib/duckdb/init_info.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DuckDB
+  #
+  # The DuckDB::InitInfo provides context during table function initialization.
+  #
+  # It is passed to the init callback to set up execution state.
+  #
+  # Example:
+  #
+  #   table_function.init do |init_info|
+  #     # Initialize execution state
+  #     # Can report errors if initialization fails
+  #     init_info.set_error('Initialization failed')
+  #   end
+  #
+  # rubocop:disable Lint/EmptyClass
+  class InitInfo
+    # All methods are defined in C extension (ext/duckdb/init_info.c)
+  end
+  # rubocop:enable Lint/EmptyClass
+end

data/lib/duckdb/instance_cache.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-if defined?(DuckDB::InstanceCache)
-
 module DuckDB
   # The DuckDB::InstanceCache is necessary if a client/program (re)opens
   # multiple databases to the same file within the same statement.
@@ -22,5 +20,3 @@ module DuckDB
     end
   end
 end
-
-end

data/lib/duckdb/interval.rb

@@ -62,7 +62,7 @@ module DuckDB
       #
       #   DuckDB::Interval.mk_interval(year: 1, month: 2, day: 3, hour: 4, min: 5, sec: 6, usec: 123456)
       #   => #<DuckDB::Interval:0x00007f9b9c0b3b60 @interval_months=14, @interval_days=3, @interval_micros=14706123456>
-      def mk_interval(year: 0, month: 0, day: 0, hour: 0, min: 0, sec: 0, usec: 0)
+      def mk_interval(year: 0, month: 0, day: 0, hour: 0, min: 0, sec: 0, usec: 0) # rubocop:disable Metrics/ParameterLists
         Interval.new(
           interval_months: (year * 12) + month,
           interval_days: day,

data/lib/duckdb/logical_type.rb

@@ -54,6 +54,47 @@ module DuckDB
       const_set(method_name.upcase, send(method_name))
     end
 
+    class << self
+      def resolve(symbol)
+        return symbol if symbol.is_a?(DuckDB::LogicalType)
+
+        DuckDB::LogicalType.const_get(symbol.upcase)
+      rescue NameError
+        raise ArgumentError, "Unknown logical type symbol: #{symbol}"
+      end
+
+      # Creates an array logical type with the given child type and size.
+      #
+      # The +type+ argument can be a symbol or a DuckDB::LogicalType instance.
+      # The +size+ argument specifies the fixed size of the array.
+      #
+      #   require 'duckdb'
+      #
+      #   array_type = DuckDB::LogicalType.create_array(:integer, 3)
+      #   array_type.type #=> :array
+      #   array_type.child_type.type #=> :integer
+      #   array_type.size #=> 3
+      def create_array(type, size)
+        _create_array_type(LogicalType.resolve(type), size)
+      end
+
+      # Creates a list logical type with the given child type.
+      #
+      # The +type+ argument can be a symbol or a DuckDB::LogicalType instance.
+      #
+      #   require 'duckdb'
+      #
+      #   list_type = DuckDB::LogicalType.create_list(:integer)
+      #   list_type.type #=> :list
+      #   list_type.child_type.type #=> :integer
+      #
+      #   nested_list = DuckDB::LogicalType.create_list(list_type)
+      #   nested_list.child_type.type #=> :list
+      def create_list(type)
+        _create_list_type(LogicalType.resolve(type))
+      end
+    end
+
     # 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.
@@ -104,7 +145,7 @@ module DuckDB
     #   names = union_logical_type.each_member_name.to_a
     #   # => ["member1", "member2"]
     def each_member_name
-      return to_enum(__method__) {member_count} unless block_given?
+      return to_enum(__method__) { member_count } unless block_given?
 
       member_count.times do |i|
         yield member_name_at(i)
@@ -126,7 +167,7 @@ module DuckDB
     #   names = union_logical_type.each_member_type.map(&:type)
     #   # => [:varchar, :integer]
     def each_member_type
-      return to_enum(__method__) {member_count} unless block_given?
+      return to_enum(__method__) { member_count } unless block_given?
 
       member_count.times do |i|
         yield member_type_at(i)
@@ -148,7 +189,7 @@ module DuckDB
     #   names = struct_logical_type.each_child_name.to_a
     #   # => ["child1", "child2"]
     def each_child_name
-      return to_enum(__method__) {child_count} unless block_given?
+      return to_enum(__method__) { child_count } unless block_given?
 
       child_count.times do |i|
         yield child_name_at(i)
@@ -170,7 +211,7 @@ module DuckDB
     #   types = struct_logical_type.each_child_type.map(&:type)
     #   # => [:integer, :varchar]
     def each_child_type
-      return to_enum(__method__) {child_count} unless block_given?
+      return to_enum(__method__) { child_count } unless block_given?
 
       child_count.times do |i|
         yield child_type_at(i)
@@ -192,7 +233,7 @@ module DuckDB
     #   values = enum_logical_type.each_value.to_a
     #   # => ["happy", "sad"]
     def each_dictionary_value
-      return to_enum(__method__) {dictionary_size} unless block_given?
+      return to_enum(__method__) { dictionary_size } unless block_given?
 
       dictionary_size.times do |i|
         yield dictionary_value_at(i)

data/lib/duckdb/prepared_statement.rb

@@ -143,7 +143,8 @@ module DuckDB
     def bind_uint64(index, val)
       return _bind_uint64(index, val) if val.between?(0, 18_446_744_073_709_551_615)
 
-      raise DuckDB::Error, "can't bind uint64(bind_uint64) to `#{val}`. The `#{val}` is out of range 0..18446744073709551615."
+      raise DuckDB::Error,
+            "can't bind uint64(bind_uint64) to `#{val}`. The `#{val}` is out of range 0..18446744073709551615."
     end
 
     # binds i-th parameter with SQL prepared statement.
@@ -319,6 +320,7 @@ module DuckDB
 
     private
 
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
     def bind_with_index(index, value)
       case value
       when NilClass
@@ -326,14 +328,9 @@ module DuckDB
       when Float
         bind_double(index, value)
       when Integer
-        case value
-        when RANGE_INT64
-          bind_int64(index, value)
-        else
-          bind_varchar(index, value.to_s)
-        end
+        bind_integer_value(index, value)
       when String
-        blob?(value) ? bind_blob(index, value) : bind_varchar(index, value)
+        bind_string_value(index, value)
       when TrueClass, FalseClass
         bind_bool(index, value)
       when Time
@@ -346,6 +343,23 @@ module DuckDB
         raise(DuckDB::Error, "not supported type `#{value}` (#{value.class})")
       end
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+    def bind_integer_value(index, value)
+      if RANGE_INT64.cover?(value)
+        bind_int64(index, value)
+      else
+        bind_varchar(index, value.to_s)
+      end
+    end
+
+    def bind_string_value(index, value)
+      if blob?(value)
+        bind_blob(index, value)
+      else
+        bind_varchar(index, value)
+      end
+    end
 
     def bind_with_name(name, value)
       raise DuckDB::Error, 'not supported binding with name' unless respond_to?(:bind_parameter_index)

data/lib/duckdb/result.rb

@@ -24,6 +24,7 @@ module DuckDB
   #   end
   class Result
     include Enumerable
+
     RETURN_TYPES = %i[invalid changed_rows nothing query_result].freeze
 
     alias column_size column_count