duckdb 1.5.3.0 → 1.5.5.0

data/lib/duckdb/value.rb

@@ -238,8 +238,408 @@ module DuckDB
         _create_decimal(lower, upper, width, value.scale)
       end
 
+      # Creates a DuckDB::Value of DATE type.
+      # The argument is parsed leniently: a Date, a Time, or a String
+      # accepted by Date.parse, matching Appender#append_date.
+      #
+      #   value = DuckDB::Value.create_date(Date.new(2026, 7, 12))
+      #   value = DuckDB::Value.create_date('2026-07-12')
+      #
+      # @param value [Date, Time, String] the date value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Date.
+      def create_date(value)
+        date = _parse_date(value)
+        _create_date(date.year, date.month, date.day)
+      end
+
+      # Creates a DuckDB::Value of TIME type (microsecond precision).
+      # The argument is parsed leniently: a Time or a String accepted by
+      # Time.parse, matching Appender#append_time.
+      #
+      #   value = DuckDB::Value.create_time(Time.now)
+      #   value = DuckDB::Value.create_time('12:34:56.789')
+      #
+      # @param value [Time, String] the time value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_time(value)
+        time = _parse_time(value)
+        _create_time(time.hour, time.min, time.sec, time.usec)
+      end
+
+      # Creates a DuckDB::Value of TIME_NS type (nanosecond precision).
+      # The argument is parsed leniently: a Time or a String accepted by
+      # Time.parse. Nanoseconds are preserved.
+      #
+      #   value = DuckDB::Value.create_time_ns(Time.now)
+      #   value = DuckDB::Value.create_time_ns('12:34:56.123456789')
+      #
+      # @param value [Time, String] the time value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_time_ns(value)
+        time = _parse_time(value)
+        _create_time_ns(time.hour, time.min, time.sec, time.nsec)
+      end
+
+      # Creates a DuckDB::Value of TIMETZ type (time with UTC offset).
+      # The argument is parsed leniently: a Time (the offset is taken from
+      # the Time) or a String accepted by Time.parse.
+      #
+      #   value = DuckDB::Value.create_time_tz(Time.now)
+      #   value = DuckDB::Value.create_time_tz('12:34:56.789012+05:30')
+      #
+      # @param value [Time, String] the time value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_time_tz(value)
+        time = _parse_time(value)
+        micros = (((((time.hour * 60) + time.min) * 60) + time.sec) * 1_000_000) + time.usec
+        _create_time_tz(micros, time.utc_offset)
+      end
+
+      # Creates a DuckDB::Value of TIMESTAMP type (microsecond precision).
+      # The argument is parsed leniently: a Time, a Date, or a String
+      # accepted by Time.parse, matching Appender#append_timestamp.
+      #
+      #   value = DuckDB::Value.create_timestamp(Time.now)
+      #   value = DuckDB::Value.create_timestamp('2026-07-12 12:34:56.789')
+      #
+      # @param value [Time, Date, String] the timestamp value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_timestamp(value)
+        time = to_time(value)
+        _create_timestamp(time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
+      end
+
+      # Creates a DuckDB::Value of TIMESTAMP_S type (second precision).
+      # The argument is parsed leniently: a Time, a Date, or a String
+      # accepted by Time.parse. Sub-second input is truncated to seconds.
+      #
+      #   value = DuckDB::Value.create_timestamp_s(Time.now)
+      #   value = DuckDB::Value.create_timestamp_s('2026-07-12 12:34:56')
+      #
+      # @param value [Time, Date, String] the timestamp value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_timestamp_s(value)
+        time = to_time(value)
+        _create_timestamp_s(time.year, time.month, time.day, time.hour, time.min, time.sec)
+      end
+
+      # Creates a DuckDB::Value of TIMESTAMP_MS type (millisecond precision).
+      # The argument is parsed leniently: a Time, a Date, or a String
+      # accepted by Time.parse. Sub-millisecond input is truncated.
+      #
+      #   value = DuckDB::Value.create_timestamp_ms(Time.now)
+      #   value = DuckDB::Value.create_timestamp_ms('2026-07-12 12:34:56.789')
+      #
+      # @param value [Time, Date, String] the timestamp value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_timestamp_ms(value)
+        time = to_time(value)
+        _create_timestamp_ms(time.year, time.month, time.day, time.hour, time.min, time.sec, time.usec)
+      end
+
+      # Creates a DuckDB::Value of TIMESTAMP_NS type (nanosecond precision).
+      # The argument is parsed leniently: a Time, a Date, or a String
+      # accepted by Time.parse. Nanoseconds are preserved.
+      #
+      #   value = DuckDB::Value.create_timestamp_ns(Time.now)
+      #   value = DuckDB::Value.create_timestamp_ns('2026-07-12 12:34:56.123456789')
+      #
+      # @param value [Time, Date, String] the timestamp value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_timestamp_ns(value)
+        time = to_time(value)
+        _create_timestamp_ns(time.year, time.month, time.day, time.hour, time.min, time.sec, time.nsec)
+      end
+
+      # Creates a DuckDB::Value of TIMESTAMP WITH TIME ZONE type.
+      # The argument is parsed leniently: a Time, a Date, or a String
+      # accepted by Time.parse. The instant is stored (as microseconds since
+      # the Unix epoch), so the input's UTC offset is honored.
+      #
+      #   value = DuckDB::Value.create_timestamp_tz(Time.now)
+      #   value = DuckDB::Value.create_timestamp_tz('2026-07-12 12:34:56.789+05:30')
+      #
+      # @param value [Time, Date, String] the timestamp value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ cannot be parsed to a Time.
+      def create_timestamp_tz(value)
+        time = to_time(value)
+        _create_timestamp_tz((time.to_i * 1_000_000) + time.usec)
+      end
+
+      # Creates a DuckDB::Value of INTERVAL type.
+      # Unlike the other temporal creators, the input is strict: it must be
+      # a DuckDB::Interval.
+      #
+      #   interval = DuckDB::Interval.new(interval_months: 14, interval_days: 3, interval_micros: 12_000_000)
+      #   value = DuckDB::Value.create_interval(interval)
+      #
+      # @param value [DuckDB::Interval] the interval value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ is not a DuckDB::Interval.
+      def create_interval(value)
+        check_type!(value, DuckDB::Interval)
+
+        _create_interval(value.interval_months, value.interval_days, value.interval_micros)
+      end
+
+      # Creates a DuckDB::Value of ENUM type.
+      # The first argument is the enum type: an Array of member names (as
+      # accepted by DuckDB::LogicalType.create_enum) or an ENUM
+      # DuckDB::LogicalType.
+      # The second argument is the member: its name (String or Symbol) or
+      # its 0-based index (Integer).
+      #
+      #   value = DuckDB::Value.create_enum(%w[happy sad neutral], 'sad')
+      #
+      #   # equivalent, with an explicit ENUM logical type:
+      #   enum_type = DuckDB::LogicalType.create_enum('happy', 'sad', 'neutral')
+      #   value = DuckDB::Value.create_enum(enum_type, 'sad')
+      #
+      # @param enum_type [Array<String>, DuckDB::LogicalType] the member names or ENUM logical type.
+      # @param member [String, Symbol, Integer] the member name or 0-based index.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if enum_type is not an Array or an ENUM
+      #   DuckDB::LogicalType, or member is not a member of the enum.
+      def create_enum(enum_type, member)
+        enum_type = DuckDB::LogicalType.create_enum(*enum_type) if enum_type.is_a?(Array)
+        check_type!(enum_type, DuckDB::LogicalType)
+        raise ArgumentError, "expected ENUM LogicalType, got #{enum_type.type}" unless enum_type.type == :enum
+
+        _create_enum(enum_type, enum_member_index(enum_type, member))
+      end
+
+      # Creates a DuckDB::Value of UNION type.
+      # The first argument is the union type: a Hash of member name to
+      # member type (as accepted by DuckDB::LogicalType.create_union) or a
+      # UNION DuckDB::LogicalType.
+      # The second argument is the member tag (String or Symbol), and the
+      # third is the member value as a DuckDB::Value of the tagged type.
+      #
+      #   value = DuckDB::Value.create_union({ num: :integer, str: :varchar }, :num, DuckDB::Value.create_int32(42))
+      #   value.to_ruby #=> 42
+      #
+      #   # equivalent, with an explicit UNION logical type:
+      #   union_type = DuckDB::LogicalType.create_union(num: :integer, str: :varchar)
+      #   value = DuckDB::Value.create_union(union_type, :num, DuckDB::Value.create_int32(42))
+      #
+      # @param union_type [Hash, DuckDB::LogicalType] the member spec or UNION logical type.
+      # @param tag [String, Symbol] the member tag.
+      # @param member_value [DuckDB::Value] the member value.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if union_type is not a Hash or a UNION
+      #   DuckDB::LogicalType, tag is not a member of the union, or
+      #   member_value is not a DuckDB::Value.
+      # @raise [DuckDB::Error] if member_value does not match the tagged
+      #   member's type.
+      def create_union(union_type, tag, member_value)
+        union_type = DuckDB::LogicalType.create_union(**union_type) if union_type.is_a?(Hash)
+        check_type!(union_type, DuckDB::LogicalType)
+        raise ArgumentError, "expected UNION LogicalType, got #{union_type.type}" unless union_type.type == :union
+
+        check_type!(member_value, DuckDB::Value)
+        tag_index = union_type.each_member_name.find_index(tag.to_s)
+        raise ArgumentError, "`#{tag}` is not a member of the union" if tag_index.nil?
+
+        _create_union(union_type, tag_index, member_value)
+      end
+
+      # Creates a DuckDB::Value of BIT (bitstring) type.
+      #
+      #   value = DuckDB::Value.create_bit('0101')
+      #
+      # @param value [String] the bitstring: '0'/'1' characters, MSB first.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ is not a non-empty String of '0'
+      #   and '1' characters.
+      def create_bit(value)
+        check_type!(value, String)
+        raise ArgumentError, "expected a String of '0'/'1' characters" unless value.match?(/\A[01]+\z/)
+
+        pad = -value.length % 8
+        _create_bit("#{pad.chr}#{[('1' * pad) + value].pack('B*')}".b)
+      end
+
+      # Creates a DuckDB::Value of BIGNUM (arbitrary-precision integer)
+      # type.
+      #
+      #   value = DuckDB::Value.create_bignum(2**200)
+      #
+      # @param value [Integer] the integer value, of arbitrary size.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [ArgumentError] if +value+ is not an Integer.
+      def create_bignum(value)
+        check_type!(value, Integer)
+
+        hex = value.abs.to_s(16)
+        hex = "0#{hex}" if hex.length.odd?
+        _create_bignum([hex].pack('H*'), value.negative?)
+      end
+
+      # Creates a DuckDB::Value of LIST type.
+      # The first argument is the element type: a Symbol (e.g. :integer) or a
+      # DuckDB::LogicalType.
+      # The second argument is an Array of DuckDB::Value elements.
+      #
+      #   values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
+      #   list = DuckDB::Value.create_list(:integer, values)
+      #
+      # @param child_type [Symbol, DuckDB::LogicalType] the element logical type.
+      # @param values [Array<DuckDB::Value>] the list elements.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [DuckDB::Error] if child_type cannot be resolved to a
+      #   DuckDB::LogicalType.
+      # @raise [ArgumentError] if values is not an Array of DuckDB::Value.
+      def create_list(child_type, values)
+        check_value_array!(values)
+
+        _create_list(DuckDB::LogicalType.resolve(child_type), values)
+      end
+
+      # Creates a DuckDB::Value of ARRAY type. The array size is the number
+      # of elements given.
+      # The first argument is the element type: a Symbol (e.g. :integer) or a
+      # DuckDB::LogicalType.
+      # The second argument is an Array of DuckDB::Value elements.
+      #
+      #   values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
+      #   array = DuckDB::Value.create_array(:integer, values)
+      #
+      # @param child_type [Symbol, DuckDB::LogicalType] the element logical type.
+      # @param values [Array<DuckDB::Value>] the array elements.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [DuckDB::Error] if child_type cannot be resolved to a
+      #   DuckDB::LogicalType.
+      # @raise [ArgumentError] if values is not an Array of DuckDB::Value.
+      def create_array(child_type, values)
+        check_value_array!(values)
+
+        _create_array(DuckDB::LogicalType.resolve(child_type), values)
+      end
+
+      # Creates a DuckDB::Value of STRUCT type.
+      # The first argument is the field spec: a Hash of field name to field
+      # type (a Symbol or a DuckDB::LogicalType, as accepted by
+      # DuckDB::LogicalType.create_struct) or a STRUCT DuckDB::LogicalType.
+      # The second argument is an Array of DuckDB::Value field values,
+      # positional, matching the struct's field order.
+      #
+      #   values = [DuckDB::Value.create_int32(1), DuckDB::Value.create_varchar('x')]
+      #   struct = DuckDB::Value.create_struct({ a: :integer, b: :varchar }, values)
+      #
+      #   # equivalent, with an explicit STRUCT logical type:
+      #   struct_type = DuckDB::LogicalType.create_struct(a: :integer, b: :varchar)
+      #   struct = DuckDB::Value.create_struct(struct_type, values)
+      #
+      # @param struct_type [Hash, DuckDB::LogicalType] the field spec or STRUCT logical type.
+      # @param values [Array<DuckDB::Value>] the field values, in field order.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [DuckDB::Error] if a field type in the Hash cannot be resolved
+      #   to a DuckDB::LogicalType.
+      # @raise [ArgumentError] if struct_type is not a Hash or a STRUCT
+      #   DuckDB::LogicalType, values is not an Array of DuckDB::Value, or
+      #   values.size does not match the struct's field count.
+      def create_struct(struct_type, values)
+        struct_type = DuckDB::LogicalType.create_struct(**struct_type) if struct_type.is_a?(Hash)
+        check_type!(struct_type, DuckDB::LogicalType)
+        raise ArgumentError, "expected STRUCT LogicalType, got #{struct_type.type}" unless struct_type.type == :struct
+
+        check_value_array!(values)
+        # The C API's duckdb_create_struct_value reads exactly child_count
+        # values from the buffer with no count argument, so a size mismatch
+        # here would cause an out-of-bounds read in C.
+        n = struct_type.child_count
+        raise ArgumentError, "expected #{n} values for STRUCT, got #{values.size}" unless values.size == n
+
+        _create_struct(struct_type, values)
+      end
+
+      # Creates a DuckDB::Value of MAP type.
+      # The first argument is the type spec: a one-pair Hash of key type to
+      # value type (each a Symbol or a DuckDB::LogicalType, as accepted by
+      # DuckDB::LogicalType.create_map) or a MAP DuckDB::LogicalType.
+      # The second argument is a Hash of DuckDB::Value keys to DuckDB::Value
+      # values.
+      #
+      #   entries = {
+      #     DuckDB::Value.create_varchar('a') => DuckDB::Value.create_int32(1),
+      #     DuckDB::Value.create_varchar('b') => DuckDB::Value.create_int32(2)
+      #   }
+      #   map = DuckDB::Value.create_map({ varchar: :integer }, entries)
+      #
+      #   # equivalent, with an explicit MAP logical type:
+      #   map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
+      #   map = DuckDB::Value.create_map(map_type, entries)
+      #
+      # @param map_type [Hash, DuckDB::LogicalType] the type spec or MAP logical type.
+      # @param entries [Hash{DuckDB::Value => DuckDB::Value}] the map entries.
+      # @return [DuckDB::Value] the created Value object.
+      # @raise [DuckDB::Error] if a type in the Hash spec cannot be resolved
+      #   to a DuckDB::LogicalType.
+      # @raise [ArgumentError] if map_type is not a one-pair Hash or a MAP
+      #   DuckDB::LogicalType, or entries is not a Hash of DuckDB::Value to
+      #   DuckDB::Value.
+      def create_map(map_type, entries)
+        map_type = resolve_map_type(map_type)
+        check_type!(entries, Hash)
+        check_value_array!(entries.keys)
+        check_value_array!(entries.values)
+
+        _create_map(map_type, entries.keys, entries.values)
+      end
+
       private
 
+      def to_time(value)
+        value.is_a?(Date) ? value.to_time : _parse_time(value)
+      end
+
+      def enum_member_index(enum_type, member)
+        case member
+        when Integer
+          check_range!(member, 0...enum_type.dictionary_size, 'ENUM index')
+          member
+        when String, Symbol
+          enum_member_index_by_name(enum_type, member)
+        else
+          raise ArgumentError, "expected String, Symbol or Integer, got #{member.class.name}"
+        end
+      end
+
+      def enum_member_index_by_name(enum_type, member)
+        index = enum_type.each_dictionary_value.find_index(member.to_s)
+        raise ArgumentError, "`#{member}` is not a member of the enum" if index.nil?
+
+        index
+      end
+
+      def resolve_map_type(map_type)
+        if map_type.is_a?(Hash)
+          unless map_type.size == 1
+            raise ArgumentError, "expected exactly one key type => value type pair, got #{map_type.size}"
+          end
+
+          map_type = DuckDB::LogicalType.create_map(*map_type.first)
+        end
+        check_type!(map_type, DuckDB::LogicalType)
+        raise ArgumentError, "expected MAP LogicalType, got #{map_type.type}" unless map_type.type == :map
+
+        map_type
+      end
+
+      def check_value_array!(values)
+        check_type!(values, Array)
+        values.each { |value| check_type!(value, DuckDB::Value) }
+      end
+
       def check_range!(value, range, type_name)
         raise ArgumentError, "value out of range for #{type_name} (#{range})" unless range.cover?(value)
       end

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 = '1.5.3.0'
+  VERSION = '1.5.5.0'
 end

data/lib/duckdb.rb

@@ -4,11 +4,13 @@ require 'duckdb/duckdb_native'
 require 'duckdb/library_version'
 require 'duckdb/version'
 require 'duckdb/converter'
+require 'duckdb/error'
 require 'duckdb/table_name_parser'
 require 'duckdb/database'
 require 'duckdb/connection'
 require 'duckdb/extracted_statements'
 require 'duckdb/result'
+require 'duckdb/arrow_array_stream'
 require 'duckdb/prepared_statement'
 require 'duckdb/pending_result'
 require 'duckdb/appender'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duckdb
 version: !ruby/object:Gem::Version
-  version: 1.5.3.0
+  version: 1.5.5.0
 platform: ruby
 authors:
 - Masaki Suketa
@@ -35,6 +35,7 @@ extra_rdoc_files: []
 files:
 - ".rdoc_options"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE
 - README.md
 - Rakefile
@@ -47,6 +48,10 @@ files:
 - ext/duckdb/aggregate_function_set.h
 - ext/duckdb/appender.c
 - ext/duckdb/appender.h
+- ext/duckdb/arrow_array_stream.c
+- ext/duckdb/arrow_array_stream.h
+- ext/duckdb/arrow_import.c
+- ext/duckdb/arrow_import.h
 - ext/duckdb/blob.c
 - ext/duckdb/blob.h
 - ext/duckdb/client_context.c
@@ -114,6 +119,7 @@ files:
 - lib/duckdb/aggregate_function.rb
 - lib/duckdb/aggregate_function_set.rb
 - lib/duckdb/appender.rb
+- lib/duckdb/arrow_array_stream.rb
 - lib/duckdb/casting.rb
 - lib/duckdb/client_context.rb
 - lib/duckdb/column.rb
@@ -124,6 +130,7 @@ files:
 - lib/duckdb/converter/int_to_sym.rb
 - lib/duckdb/data_chunk.rb
 - lib/duckdb/database.rb
+- lib/duckdb/error.rb
 - lib/duckdb/expression.rb
 - lib/duckdb/extracted_statements.rb
 - lib/duckdb/function_type_validation.rb
@@ -162,14 +169,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Ruby bindings for the DuckDB database engine.
 test_files: []