duckdb 1.5.3.0 → 1.5.5.0

data/lib/duckdb/connection.rb

@@ -383,8 +383,81 @@ module DuckDB
       register_table_function(tf)
     end
 
+    # [EXPERIMENTAL] Appends an Arrow producer into an existing table.
+    #
+    # Reads +producer+ (any object responding to +#arrow_c_stream+, such as a
+    # ruby-polars +DataFrame+ or a +DuckDB::Result+) as an Arrow C stream and
+    # appends its chunks into the existing table +table+. The producer's Arrow
+    # columns must line up with the table's columns positionally and by count.
+    # DuckDB casts compatible column types (e.g. INTEGER into a BIGINT column);
+    # a type that cannot be cast (e.g. a non-numeric VARCHAR into an INTEGER
+    # column) or a column-count mismatch raises +DuckDB::Error+.
+    #
+    # This is not transactional: a schema mismatch fails before any rows are
+    # written, but a rarer mid-stream failure can leave earlier chunks
+    # appended. Wrap the call in your own transaction for all-or-nothing.
+    #
+    # This API is built on DuckDB's unstable Arrow C API and may change in any
+    # minor release.
+    #
+    # @param table [String] the name of the existing target table
+    # @param producer [#arrow_c_stream] the Arrow producer
+    # @raise [TypeError] if +producer+ does not respond to +#arrow_c_stream+
+    # @return [Integer] the number of rows appended
+    #
+    # @example Load a Polars DataFrame into a table
+    #   con.query('CREATE TABLE t (id INTEGER, name VARCHAR)')
+    #   con.append_arrow('t', polars_df)
+    #
+    def append_arrow(table, producer)
+      unless producer.respond_to?(:arrow_c_stream)
+        raise TypeError, "Arrow producer must respond to #arrow_c_stream, got #{producer.class}"
+      end
+
+      stream = producer.arrow_c_stream # keep the producer's stream alive for the duration
+      address = stream.to_i
+      begin
+        append_arrow_chunks(table, address)
+      ensure
+        _arrow_release(address)
+      end
+    end
+
+    # Returns the names of the tables referenced by the given SQL query,
+    # without executing it.
+    #
+    # @param query [String] the SQL query to inspect
+    # @param qualified [Boolean] if true, returns each table reference as
+    #   written in the query, keeping any catalog/schema qualification;
+    #   if false (default), bare table names only
+    # @return [Array<String>] the referenced table names, in unspecified order
+    # @raise [DuckDB::Error] if the query cannot be parsed
+    #
+    # @example
+    #   con.table_names('SELECT * FROM users u JOIN orders o ON u.id = o.user_id').sort
+    #   #=> ["orders", "users"]
+    #   con.table_names('SELECT * FROM memory.main.users', qualified: true)
+    #   #=> ["memory.main.users"]
+    def table_names(query, qualified: false)
+      _get_table_names(query, qualified).to_ruby
+    end
+
     private
 
+    # Drives the Arrow stream at +address+ chunk by chunk into +table+,
+    # returning the number of rows appended.
+    def append_arrow_chunks(table, address)
+      converted_schema = _arrow_converted_schema(address)
+      rows = 0
+      appender(table) do |app|
+        while (chunk = _arrow_next_chunk(address, converted_schema))
+          rows += chunk.size
+          app.append_data_chunk(chunk)
+        end
+      end
+      rows
+    end
+
     def run_appender_block(appender, &)
       return appender unless block_given?
 

data/lib/duckdb/converter/int_to_sym.rb

@@ -73,11 +73,64 @@ module DuckDB
         35 => :bignum,
         36 => :sqlnull,
         37 => :string_literal,
-        38 => :integer_literal
+        38 => :integer_literal,
+        39 => :time_ns
       }.freeze
 
+      ERROR_TYPES = %i[
+        invalid
+        out_of_range
+        conversion
+        unknown_type
+        decimal
+        mismatch_type
+        divide_by_zero
+        object_size
+        invalid_type
+        serialization
+        transaction
+        not_implemented
+        expression
+        catalog
+        parser
+        planner
+        scheduler
+        executor
+        constraint
+        index
+        stat
+        connection
+        syntax
+        settings
+        binder
+        network
+        optimizer
+        null_pointer
+        io
+        interrupt
+        fatal
+        internal
+        invalid_input
+        out_of_memory
+        permission
+        parameter_not_resolved
+        parameter_not_allowed
+        dependency
+        http
+        missing_extension
+        autoload
+        sequence
+        invalid_configuration
+      ].freeze
+
       module_function
 
+      def error_type_to_sym(val) # :nodoc:
+        raise DuckDB::Error, "Unknown error type: #{val}" if val >= ERROR_TYPES.size
+
+        ERROR_TYPES[val]
+      end
+
       def statement_type_to_sym(val) # :nodoc:
         raise DuckDB::Error, "Unknown statement type: #{val}" if val >= STATEMENT_TYPES.size
 

data/lib/duckdb/converter.rb

@@ -83,18 +83,18 @@ module DuckDB
 
     def _to_time_from_duckdb_timestamp_ns(time)
       _to_time_from_duckdb_timestamp_s(time / 1_000_000_000).then do |tm|
-        _to_time(tm.year, tm.month, tm.day, tm.hour, tm.min, tm.sec, time % 1_000_000_000 / 1000)
+        _to_time(tm.year, tm.month, tm.day, tm.hour, tm.min, tm.sec, Rational(time % 1_000_000_000, 1000))
       end
     end
 
     def _to_time_from_duckdb_time_ns(nanos)
       hour = nanos / 3_600_000_000_000
-      nanos %= 3_600_000_000_000
-      min = nanos / 60_000_000_000
-      nanos %= 60_000_000_000
-      sec = nanos / 1_000_000_000
-      microsecond = (nanos % 1_000_000_000) / 1_000
-      _to_time_from_duckdb_time(hour, min, sec, microsecond)
+      min = nanos % 3_600_000_000_000 / 60_000_000_000
+      sec = nanos % 60_000_000_000 / 1_000_000_000
+      nsec = nanos % 1_000_000_000
+      return Time.utc(1970, 1, 1, hour, min, sec, Rational(nsec, 1_000)) if default_timezone_utc?
+
+      Time.parse(format('%<hour>02d:%<min>02d:%<sec>02d.%<nsec>09d', hour: hour, min: min, sec: sec, nsec: nsec))
     end
 
     def _to_time_from_duckdb_time_tz(hour, min, sec, micro, timezone)

data/lib/duckdb/error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DuckDB
+  # The exception raised by ruby-duckdb.
+  class Error < StandardError
+    # +error_type_id+ is the raw DuckDB error type id, set by the C extension when
+    # a query result fails; it defaults to +nil+ for all other errors.
+    def initialize(message = nil, error_type_id = nil)
+      super(message)
+      @error_type_id = error_type_id
+    end
+
+    # Returns the DuckDB error category as a Symbol (e.g. +:constraint+,
+    # +:catalog+, +:parser+), or +nil+ when the error did not originate from a
+    # DuckDB query result (e.g. internal binding failures).
+    #
+    #   begin
+    #     con.query('INSERT INTO t VALUES (1)') # duplicate primary key
+    #   rescue DuckDB::Error => e
+    #     e.error_type # => :constraint
+    #   end
+    def error_type
+      @error_type_id && Converter::IntToSym.error_type_to_sym(@error_type_id)
+    end
+  end
+end

data/lib/duckdb/function_type_validation.rb

@@ -23,6 +23,7 @@ module DuckDB
       timestamp_s
       timestamp_ms
       timestamp_ns
+      time_ns
       time_tz
       timestamp_tz
       tinyint

data/lib/duckdb/logical_type.rb

@@ -7,7 +7,7 @@ module DuckDB
 
     @logical_types = {}
 
-    {
+    types = {
       boolean: 1,
       tinyint: 2,
       smallint: 3,
@@ -47,8 +47,11 @@ module DuckDB
       sqlnull: 36,
       string_literal: 37,
       integer_literal: 38
-      # time_ns: 39
-    }.each do |method_name, type_id|
+    }
+    # duckdb_create_logical_type rejects TIME_NS on DuckDB < 1.5.0.
+    types[:time_ns] = 39 if Gem::Version.new(DuckDB::LIBRARY_VERSION) >= Gem::Version.new('1.5.0')
+
+    types.each do |method_name, type_id|
       define_singleton_method(method_name) do
         @logical_types[type_id] ||= DuckDB::LogicalType.new(type_id)
       end

data/lib/duckdb/prepared_statement.rb

@@ -76,6 +76,21 @@ module DuckDB
       Converter::IntToSym.type_to_sym(i)
     end
 
+    # returns the column type of the result set of the prepared statement
+    # without executing it. The argument is the column index (0-based).
+    # Returns :invalid if the column index is out of range.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.execute('CREATE TABLE users (id INTEGER, name VARCHAR(255))')
+    #   stmt = con.prepared_statement('SELECT * FROM users')
+    #   stmt.column_type(0) # => :integer
+    def column_type(index)
+      i = _column_type(index)
+      Converter::IntToSym.type_to_sym(i)
+    end
+
     # binds all parameters with SQL prepared statement.
     #
     #   require 'duckdb'
@@ -193,6 +208,23 @@ module DuckDB
       _bind_uhugeint(index, lower, upper)
     end
 
+    # binds i-th parameter with a UUID value.
+    # The first argument is the index of the parameter (1-based).
+    # The second argument must be a String in canonical UUID format
+    # (<tt>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</tt>).
+    # Raises ArgumentError if the value is not a valid UUID string.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE uuids (id UUID)')
+    #   stmt = DuckDB::PreparedStatement.new(con, 'INSERT INTO uuids(id) VALUES ($1)')
+    #   stmt.bind_uuid(1, '550e8400-e29b-41d4-a716-446655440000')
+    #   stmt.execute
+    def bind_uuid(index, value)
+      _bind_uuid(index, value)
+    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.

data/lib/duckdb/scalar_function.rb

@@ -96,8 +96,8 @@ module DuckDB
 
     # Adds a parameter to the scalar function.
     # Currently supports BIGINT, BLOB, BOOLEAN, DATE, DECIMAL, DOUBLE, FLOAT, HUGEINT, INTEGER, INTERVAL, SMALLINT,
-    # TIME, TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, TIME_TZ, TIMESTAMP_TZ, TINYINT, UBIGINT, UHUGEINT,
-    # UINTEGER, USMALLINT, UTINYINT, UUID, and VARCHAR types.
+    # TIME, TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, TIME_NS, TIME_TZ, TIMESTAMP_TZ, TINYINT, UBIGINT,
+    # UHUGEINT, UINTEGER, USMALLINT, UTINYINT, UUID, and VARCHAR types.
     # For DECIMAL, pass a DuckDB::LogicalType instance created with DuckDB::LogicalType.create_decimal(width, scale).
     #
     # @param logical_type [DuckDB::LogicalType | :logical_type_symbol] the parameter type
@@ -111,8 +111,8 @@ module DuckDB
 
     # Sets the return type for the scalar function.
     # Currently supports BIGINT, BLOB, BOOLEAN, DATE, DECIMAL, DOUBLE, FLOAT, HUGEINT, INTEGER, INTERVAL, SMALLINT,
-    # TIME, TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, TIME_TZ, TIMESTAMP_TZ, TINYINT, UBIGINT, UHUGEINT,
-    # UINTEGER, USMALLINT, UTINYINT, UUID, and VARCHAR types.
+    # TIME, TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, TIME_NS, TIME_TZ, TIMESTAMP_TZ, TINYINT, UBIGINT,
+    # UHUGEINT, UINTEGER, USMALLINT, UTINYINT, UUID, and VARCHAR types.
     # For DECIMAL, pass a DuckDB::LogicalType instance created with DuckDB::LogicalType.create_decimal(width, scale).
     #
     # @param logical_type [DuckDB::LogicalType | :logical_type_symbol] the return type
@@ -144,8 +144,8 @@ module DuckDB
     # (e.g. a separator followed by a variable list of values).
     # The block receives fixed parameters positionally, then varargs as a splat (|fixed, *rest|).
     # Currently supports BIGINT, BLOB, BOOLEAN, DATE, DECIMAL, DOUBLE, FLOAT, HUGEINT, INTEGER, INTERVAL, SMALLINT,
-    # TIME, TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, TIME_TZ, TIMESTAMP_TZ, TINYINT, UBIGINT, UHUGEINT,
-    # UINTEGER, USMALLINT, UTINYINT, UUID, and VARCHAR types.
+    # TIME, TIMESTAMP, TIMESTAMP_S, TIMESTAMP_MS, TIMESTAMP_NS, TIME_NS, TIME_TZ, TIMESTAMP_TZ, TINYINT, UBIGINT,
+    # UHUGEINT, UINTEGER, USMALLINT, UTINYINT, UUID, and VARCHAR types.
     # For DECIMAL, pass a DuckDB::LogicalType instance created with DuckDB::LogicalType.create_decimal(width, scale).
     #
     # @param logical_type [DuckDB::LogicalType | :logical_type_symbol] the varargs element type