duckdb 1.5.4.0 → 1.5.5.0

data/ext/duckdb/value.c

@@ -21,7 +21,34 @@ static VALUE value_s__create_blob(VALUE klass, VALUE str);
 static VALUE value_s__create_hugeint(VALUE klass, VALUE lower, VALUE upper);
 static VALUE value_s__create_uhugeint(VALUE klass, VALUE lower, VALUE upper);
 static VALUE value_s__create_decimal(VALUE klass, VALUE lower, VALUE upper, VALUE width, VALUE scale);
+static VALUE value_s__create_date(VALUE klass, VALUE year, VALUE month, VALUE day);
+static VALUE value_s__create_time(VALUE klass, VALUE hour, VALUE min, VALUE sec, VALUE micros);
+static VALUE value_s__create_time_ns(VALUE klass, VALUE hour, VALUE min, VALUE sec, VALUE nanos);
+static VALUE value_s__create_time_tz(VALUE klass, VALUE micros, VALUE offset);
+static VALUE value_s__create_timestamp(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros);
+static VALUE value_s__create_timestamp_s(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec);
+static VALUE value_s__create_timestamp_ms(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros);
+static VALUE value_s__create_timestamp_ns(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE nanos);
+static VALUE value_s__create_timestamp_tz(VALUE klass, VALUE micros);
+static VALUE value_s__create_interval(VALUE klass, VALUE months, VALUE days, VALUE micros);
+static VALUE value_s__create_enum(VALUE klass, VALUE ltype, VALUE index);
+static VALUE value_s__create_union(VALUE klass, VALUE ltype, VALUE tag_index, VALUE member);
+static VALUE value_s__create_bit(VALUE klass, VALUE data);
+static VALUE value_s__create_bignum(VALUE klass, VALUE data, VALUE is_negative);
 static VALUE value_s_create_null(VALUE klass);
+static VALUE to_ruby_via_vector(duckdb_logical_type logical_type, duckdb_value val);
+static idx_t marshal_values(VALUE ary, duckdb_value **out, volatile VALUE *guard);
+static VALUE value_s__create_list(VALUE klass, VALUE ltype, VALUE values);
+static VALUE value_s__create_array(VALUE klass, VALUE ltype, VALUE values);
+static VALUE value_s__create_struct(VALUE klass, VALUE ltype, VALUE values);
+static VALUE value_s__create_map(VALUE klass, VALUE ltype, VALUE keys, VALUE values);
+static VALUE value_list_size(VALUE self);
+static VALUE value_list_child(VALUE self, VALUE vidx);
+static VALUE value_struct_child(VALUE self, VALUE vidx);
+static VALUE value_map_size(VALUE self);
+static VALUE value_map_key(VALUE self, VALUE vidx);
+static VALUE value_map_value(VALUE self, VALUE vidx);
+static VALUE value_to_ruby(VALUE self);
 
 static const rb_data_type_t value_data_type = {
     "DuckDB/Value",
@@ -140,6 +167,136 @@ static VALUE value_s__create_decimal(VALUE klass, VALUE lower, VALUE upper, VALU
     return rbduckdb_value_new(value);
 }
 
+/* :nodoc: */
+static VALUE value_s__create_date(VALUE klass, VALUE year, VALUE month, VALUE day) {
+    duckdb_value value = duckdb_create_date(rbduckdb_to_duckdb_date_from_value(year, month, day));
+    return rbduckdb_value_new(value);
+}
+
+/* :nodoc: */
+static VALUE value_s__create_time(VALUE klass, VALUE hour, VALUE min, VALUE sec, VALUE micros) {
+    duckdb_value value = duckdb_create_time(rbduckdb_to_duckdb_time_from_value(hour, min, sec, micros));
+    return rbduckdb_value_new(value);
+}
+
+/* :nodoc: */
+static VALUE value_s__create_time_ns(VALUE klass, VALUE hour, VALUE min, VALUE sec, VALUE nanos) {
+    duckdb_time_ns time_ns = rbduckdb_to_duckdb_time_ns_from_value(hour, min, sec, nanos);
+
+    return rbduckdb_value_new(duckdb_create_time_ns(time_ns));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_time_tz(VALUE klass, VALUE micros, VALUE offset) {
+    duckdb_time_tz time_tz = duckdb_create_time_tz(NUM2LL(micros), NUM2INT(offset));
+    return rbduckdb_value_new(duckdb_create_time_tz_value(time_tz));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_timestamp(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros) {
+    duckdb_timestamp timestamp = rbduckdb_to_duckdb_timestamp_from_value(year, month, day, hour, min, sec, micros);
+    return rbduckdb_value_new(duckdb_create_timestamp(timestamp));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_timestamp_s(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec) {
+    duckdb_timestamp_s ts;
+
+    ts.seconds = rbduckdb_to_duckdb_timestamp_from_value(year, month, day, hour, min, sec, INT2FIX(0)).micros / 1000000;
+    return rbduckdb_value_new(duckdb_create_timestamp_s(ts));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_timestamp_ms(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE micros) {
+    duckdb_timestamp_ms ts;
+
+    ts.millis = rbduckdb_to_duckdb_timestamp_from_value(year, month, day, hour, min, sec, micros).micros / 1000;
+    return rbduckdb_value_new(duckdb_create_timestamp_ms(ts));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_timestamp_ns(VALUE klass, VALUE year, VALUE month, VALUE day, VALUE hour, VALUE min, VALUE sec, VALUE nanos) {
+    duckdb_timestamp_ns ts;
+
+    ts.nanos = rbduckdb_to_duckdb_timestamp_from_value(year, month, day, hour, min, sec, INT2FIX(0)).micros * 1000 + NUM2LL(nanos);
+    return rbduckdb_value_new(duckdb_create_timestamp_ns(ts));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_timestamp_tz(VALUE klass, VALUE micros) {
+    duckdb_timestamp ts;
+
+    ts.micros = NUM2LL(micros);
+    return rbduckdb_value_new(duckdb_create_timestamp_tz(ts));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_interval(VALUE klass, VALUE months, VALUE days, VALUE micros) {
+    duckdb_interval interval;
+
+    rbduckdb_to_duckdb_interval_from_value(&interval, months, days, micros);
+    return rbduckdb_value_new(duckdb_create_interval(interval));
+}
+
+/* :nodoc: */
+static VALUE value_s__create_enum(VALUE klass, VALUE ltype, VALUE index) {
+    duckdb_logical_type type = rbduckdb_get_struct_logical_type(ltype)->logical_type;
+    duckdb_value value = duckdb_create_enum_value(type, NUM2ULL(index));
+
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create ENUM value");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/* :nodoc: */
+static VALUE value_s__create_union(VALUE klass, VALUE ltype, VALUE tag_index, VALUE member) {
+    duckdb_logical_type type = rbduckdb_get_struct_logical_type(ltype)->logical_type;
+    duckdb_value value = duckdb_create_union_value(type, (idx_t)NUM2ULL(tag_index), rbduckdb_get_struct_value(member)->value);
+
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create UNION value (mismatched member type?)");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/*
+ * :nodoc:
+ * data is the raw DuckDB BIT blob built in Ruby: one byte holding the
+ * number of padding bits, then the bits MSB-first with the padding bits
+ * of the first data byte set to 1.
+ */
+static VALUE value_s__create_bit(VALUE klass, VALUE data) {
+    duckdb_bit bit;
+    duckdb_value value;
+
+    bit.data = (uint8_t *)StringValuePtr(data);
+    bit.size = RSTRING_LEN(data);
+    value = duckdb_create_bit(bit);
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create BIT value");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/*
+ * :nodoc:
+ * data is the magnitude in big-endian bytes, built in Ruby.
+ */
+static VALUE value_s__create_bignum(VALUE klass, VALUE data, VALUE is_negative) {
+    duckdb_bignum bignum;
+    duckdb_value value;
+
+    bignum.data = (uint8_t *)StringValuePtr(data);
+    bignum.size = RSTRING_LEN(data);
+    bignum.is_negative = RTEST(is_negative);
+    value = duckdb_create_bignum(bignum);
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create BIGNUM value");
+    }
+    return rbduckdb_value_new(value);
+}
+
 /*
  * call-seq:
  *   DuckDB::Value.create_null -> DuckDB::Value
@@ -154,6 +311,231 @@ static VALUE value_s_create_null(VALUE klass) {
     return rbduckdb_value_new(value);
 }
 
+/*
+ * Fills *out with the unwrapped duckdb_values of a Ruby Array of
+ * DuckDB::Value objects and returns the array length. The buffer is
+ * an ALLOCV tmpbuf; the caller must call ALLOCV_END(*guard) after use.
+ * The buffer is non-NULL even for an empty array because
+ * duckdb_create_*_value functions reject a NULL values pointer.
+ *
+ * This always allocates via rb_alloc_tmp_buffer2 (heap-backed)
+ * rather than the ALLOCV_N macro, because that macro's small-size fast
+ * path uses alloca() in *this* function's stack frame: the returned
+ * pointer would dangle once marshal_values returns, and a second call
+ * (e.g. keys then values for MAP) would silently reuse and clobber the
+ * same stack slot as the first call's "buffer".
+ */
+static idx_t marshal_values(VALUE ary, duckdb_value **out, volatile VALUE *guard) {
+    idx_t n = (idx_t)RARRAY_LEN(ary);
+    idx_t count = n == 0 ? 1 : n;
+    duckdb_value *buf = (duckdb_value *)rb_alloc_tmp_buffer2(guard, (long)count, sizeof(duckdb_value));
+    idx_t i;
+
+    for (i = 0; i < n; i++) {
+        buf[i] = rbduckdb_get_struct_value(RARRAY_AREF(ary, i))->value;
+    }
+    *out = buf;
+    return n;
+}
+
+/* :nodoc: */
+static VALUE value_s__create_list(VALUE klass, VALUE ltype, VALUE values) {
+    duckdb_logical_type type = rbduckdb_get_struct_logical_type(ltype)->logical_type;
+    duckdb_value *buf;
+    volatile VALUE guard;
+    idx_t n = marshal_values(values, &buf, &guard);
+    duckdb_value value = duckdb_create_list_value(type, buf, n);
+
+    RB_GC_GUARD(values);
+    ALLOCV_END(guard);
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create LIST value");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/* :nodoc: */
+static VALUE value_s__create_array(VALUE klass, VALUE ltype, VALUE values) {
+    duckdb_logical_type type = rbduckdb_get_struct_logical_type(ltype)->logical_type;
+    duckdb_value *buf;
+    volatile VALUE guard;
+    idx_t n = marshal_values(values, &buf, &guard);
+    duckdb_value value = duckdb_create_array_value(type, buf, n);
+
+    RB_GC_GUARD(values);
+    ALLOCV_END(guard);
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create ARRAY value");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/* :nodoc: */
+static VALUE value_s__create_struct(VALUE klass, VALUE ltype, VALUE values) {
+    duckdb_logical_type type = rbduckdb_get_struct_logical_type(ltype)->logical_type;
+    duckdb_value *buf;
+    volatile VALUE guard;
+    idx_t n = marshal_values(values, &buf, &guard);
+    duckdb_value value = duckdb_create_struct_value(type, buf);
+
+    (void)n;
+    RB_GC_GUARD(values);
+    ALLOCV_END(guard);
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create STRUCT value");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/* :nodoc: */
+static VALUE value_s__create_map(VALUE klass, VALUE ltype, VALUE keys, VALUE values) {
+    duckdb_logical_type type = rbduckdb_get_struct_logical_type(ltype)->logical_type;
+    duckdb_value *kbuf;
+    duckdb_value *vbuf;
+    volatile VALUE kguard;
+    volatile VALUE vguard;
+    idx_t n = marshal_values(keys, &kbuf, &kguard);
+    duckdb_value value;
+
+    marshal_values(values, &vbuf, &vguard);   /* same length, validated in Ruby */
+    value = duckdb_create_map_value(type, kbuf, vbuf, n);
+    RB_GC_GUARD(keys);
+    RB_GC_GUARD(values);
+    ALLOCV_END(kguard);
+    ALLOCV_END(vguard);
+    if (value == NULL) {
+        rb_raise(eDuckDBError, "failed to create MAP value");
+    }
+    return rbduckdb_value_new(value);
+}
+
+/*
+ *  call-seq:
+ *    value.list_size -> Integer
+ *
+ *  Returns the number of elements of a LIST value.
+ *
+ *    require 'duckdb'
+ *    child_type = DuckDB::LogicalType.resolve(:integer)
+ *    values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
+ *    list = DuckDB::Value.create_list(child_type, values)
+ *    list.list_size # => 3
+ */
+static VALUE value_list_size(VALUE self) {
+    return ULL2NUM(duckdb_get_list_size(rbduckdb_get_struct_value(self)->value));
+}
+
+/*
+ *  call-seq:
+ *    value.list_child(index) -> DuckDB::Value
+ *
+ *  Returns the element at the specified index (0-based) of a LIST value
+ *  as a DuckDB::Value.
+ *  Raises IndexError if the index is out of range or the value is not a LIST.
+ *
+ *    require 'duckdb'
+ *    child_type = DuckDB::LogicalType.resolve(:integer)
+ *    values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
+ *    list = DuckDB::Value.create_list(child_type, values)
+ *    list.list_child(0) # => DuckDB::Value
+ */
+static VALUE value_list_child(VALUE self, VALUE vidx) {
+    duckdb_value child = duckdb_get_list_child(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));
+
+    if (child == NULL) {
+        rb_raise(rb_eIndexError, "list index out of range (or the value is not a LIST)");
+    }
+    return rbduckdb_value_new(child);
+}
+
+/*
+ *  call-seq:
+ *    value.struct_child(index) -> DuckDB::Value
+ *
+ *  Returns the field at the specified index (0-based) of a STRUCT value
+ *  as a DuckDB::Value.
+ *  Raises IndexError if the index is out of range or the value is not a STRUCT.
+ *
+ *    require 'duckdb'
+ *    struct_type = DuckDB::LogicalType.create_struct(a: :integer, b: :varchar)
+ *    values = [DuckDB::Value.create_int32(1), DuckDB::Value.create_varchar('x')]
+ *    struct = DuckDB::Value.create_struct(struct_type, values)
+ *    struct.struct_child(0) # => DuckDB::Value
+ */
+static VALUE value_struct_child(VALUE self, VALUE vidx) {
+    duckdb_value child = duckdb_get_struct_child(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));
+
+    if (child == NULL) {
+        rb_raise(rb_eIndexError, "struct index out of range (or the value is not a STRUCT)");
+    }
+    return rbduckdb_value_new(child);
+}
+
+/*
+ *  call-seq:
+ *    value.map_size -> Integer
+ *
+ *  Returns the number of entries of a MAP value.
+ *
+ *    require 'duckdb'
+ *    map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
+ *    keys = [DuckDB::Value.create_varchar('a')]
+ *    values = [DuckDB::Value.create_int32(1)]
+ *    map = DuckDB::Value.create_map(map_type, keys, values)
+ *    map.map_size # => 1
+ */
+static VALUE value_map_size(VALUE self) {
+    return ULL2NUM(duckdb_get_map_size(rbduckdb_get_struct_value(self)->value));
+}
+
+/*
+ *  call-seq:
+ *    value.map_key(index) -> DuckDB::Value
+ *
+ *  Returns the key at the specified index (0-based) of a MAP value
+ *  as a DuckDB::Value.
+ *  Raises IndexError if the index is out of range or the value is not a MAP.
+ *
+ *    require 'duckdb'
+ *    map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
+ *    keys = [DuckDB::Value.create_varchar('a')]
+ *    values = [DuckDB::Value.create_int32(1)]
+ *    map = DuckDB::Value.create_map(map_type, keys, values)
+ *    map.map_key(0) # => DuckDB::Value
+ */
+static VALUE value_map_key(VALUE self, VALUE vidx) {
+    duckdb_value child = duckdb_get_map_key(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));
+
+    if (child == NULL) {
+        rb_raise(rb_eIndexError, "map index out of range (or the value is not a MAP)");
+    }
+    return rbduckdb_value_new(child);
+}
+
+/*
+ *  call-seq:
+ *    value.map_value(index) -> DuckDB::Value
+ *
+ *  Returns the value at the specified index (0-based) of a MAP value
+ *  as a DuckDB::Value.
+ *  Raises IndexError if the index is out of range or the value is not a MAP.
+ *
+ *    require 'duckdb'
+ *    map_type = DuckDB::LogicalType.create_map(:varchar, :integer)
+ *    keys = [DuckDB::Value.create_varchar('a')]
+ *    values = [DuckDB::Value.create_int32(1)]
+ *    map = DuckDB::Value.create_map(map_type, keys, values)
+ *    map.map_value(0) # => DuckDB::Value
+ */
+static VALUE value_map_value(VALUE self, VALUE vidx) {
+    duckdb_value child = duckdb_get_map_value(rbduckdb_get_struct_value(self)->value, (idx_t)NUM2ULL(vidx));
+
+    if (child == NULL) {
+        rb_raise(rb_eIndexError, "map index out of range (or the value is not a MAP)");
+    }
+    return rbduckdb_value_new(child);
+}
+
 VALUE rbduckdb_value_new(duckdb_value value) {
     rubyDuckDBValue *ctx;
     VALUE obj = allocate(cDuckDBValue);
@@ -168,12 +550,38 @@ rubyDuckDBValue *rbduckdb_get_struct_value(VALUE obj) {
     return ctx;
 }
 
+/*
+ * Converts a duckdb_value to Ruby by referencing it into a one-element
+ * vector and reusing the vector read path, so Value#to_ruby returns the
+ * same Ruby object a query result produces for that type. Used for types
+ * the C API has no direct duckdb_get_* accessors for.
+ */
+static VALUE to_ruby_via_vector(duckdb_logical_type logical_type, duckdb_value val) {
+    duckdb_vector vec = duckdb_create_vector(logical_type, 1);
+    VALUE result;
+
+    duckdb_vector_reference_value(vec, val);
+    result = rbduckdb_vector_value_at(vec, logical_type, 0);
+    duckdb_destroy_vector(&vec);
+    return result;
+}
+
 VALUE rbduckdb_duckdb_value_to_ruby(duckdb_value val) {
     duckdb_logical_type logical_type;
     duckdb_type type_id;
+    duckdb_value child_value;
     VALUE result;
+    VALUE elem;
+    VALUE key;
     char *str;
+    idx_t i;
+    idx_t size;
+
+    if (duckdb_is_null_value(val)) {
+        return Qnil;
+    }
 
+    /* logical_type from duckdb_get_value_type is borrowed and must not be destroyed */
     logical_type = duckdb_get_value_type(val);
     type_id = duckdb_get_type_id(logical_type);
 
@@ -255,6 +663,73 @@ VALUE rbduckdb_duckdb_value_to_ruby(duckdb_value val) {
         case DUCKDB_TYPE_UUID:
             result = rbduckdb_uuid_uhugeint_to_ruby(duckdb_get_uuid(val));
             break;
+        case DUCKDB_TYPE_ENUM:
+            str = duckdb_enum_dictionary_value(logical_type, duckdb_get_enum_value(val));
+            if (str == NULL) {
+                result = Qnil;
+                break;
+            }
+            result = rb_utf8_str_new_cstr(str);
+            duckdb_free(str);
+            break;
+        case DUCKDB_TYPE_LIST:
+            size = duckdb_get_list_size(val);
+            result = rb_ary_new_capa(size);
+            for (i = 0; i < size; i++) {
+                child_value = duckdb_get_list_child(val, i);
+                elem = rbduckdb_duckdb_value_to_ruby(child_value);
+                duckdb_destroy_value(&child_value);
+                rb_ary_push(result, elem);
+            }
+            break;
+        case DUCKDB_TYPE_STRUCT:
+            size = duckdb_struct_type_child_count(logical_type);
+            result = rb_hash_new();
+            for (i = 0; i < size; i++) {
+                str = duckdb_struct_type_child_name(logical_type, i);
+                child_value = duckdb_get_struct_child(val, i);
+                elem = rbduckdb_duckdb_value_to_ruby(child_value);
+                duckdb_destroy_value(&child_value);
+                rb_hash_aset(result, ID2SYM(rb_intern(str)), elem);
+                duckdb_free(str);
+            }
+            break;
+        case DUCKDB_TYPE_MAP:
+            size = duckdb_get_map_size(val);
+            result = rb_hash_new();
+            for (i = 0; i < size; i++) {
+                child_value = duckdb_get_map_key(val, i);
+                key = rbduckdb_duckdb_value_to_ruby(child_value);
+                duckdb_destroy_value(&child_value);
+                child_value = duckdb_get_map_value(val, i);
+                elem = rbduckdb_duckdb_value_to_ruby(child_value);
+                duckdb_destroy_value(&child_value);
+                rb_hash_aset(result, key, elem);
+            }
+            break;
+        case DUCKDB_TYPE_ARRAY:
+        case DUCKDB_TYPE_UNION:
+        case DUCKDB_TYPE_BIT:
+        case DUCKDB_TYPE_DECIMAL:
+            result = to_ruby_via_vector(logical_type, val);
+            break;
+        case DUCKDB_TYPE_BLOB: {
+            duckdb_blob blob = duckdb_get_blob(val);
+
+            result = rb_str_new((const char *)blob.data, blob.size);
+            duckdb_free(blob.data);
+            break;
+        }
+        case DUCKDB_TYPE_BIGNUM: {
+            duckdb_bignum bignum = duckdb_get_bignum(val);
+
+            result = rb_integer_unpack(bignum.data, bignum.size, 1, 0, INTEGER_PACK_BIG_ENDIAN);
+            duckdb_free(bignum.data);
+            if (bignum.is_negative) {
+                result = rb_funcall(result, rb_intern("-@"), 0);
+            }
+            break;
+        }
         default:
             result = Qnil;
             break;
@@ -263,6 +738,31 @@ VALUE rbduckdb_duckdb_value_to_ruby(duckdb_value val) {
     return result;
 }
 
+/*
+ *  call-seq:
+ *    value.to_ruby -> Object
+ *
+ *  Converts the DuckDB::Value to a Ruby object. Scalar types are converted
+ *  to their natural Ruby classes. LIST and ARRAY values are converted to
+ *  Array recursively. STRUCT and MAP values are converted to Hash
+ *  recursively (STRUCT keys are Symbols; MAP keys keep their natural Ruby
+ *  type). ENUM values are converted to the member String. UNION values
+ *  are converted to the member's Ruby value. BIT values are converted to
+ *  a String of '0'/'1' characters. BIGNUM values are converted to
+ *  Integer. BLOB values are converted to a BINARY-encoded String.
+ *  DECIMAL values are converted to BigDecimal. NULL is converted to nil.
+ *  Returns nil for unsupported types.
+ *
+ *    require 'duckdb'
+ *    child_type = DuckDB::LogicalType.resolve(:integer)
+ *    values = [1, 2, 3].map { |i| DuckDB::Value.create_int32(i) }
+ *    list = DuckDB::Value.create_list(child_type, values)
+ *    list.to_ruby # => [1, 2, 3]
+ */
+static VALUE value_to_ruby(VALUE self) {
+    return rbduckdb_duckdb_value_to_ruby(rbduckdb_get_struct_value(self)->value);
+}
+
 void rbduckdb_init_value(void) {
 #if 0
     VALUE mDuckDB = rb_define_module("DuckDB");
@@ -286,6 +786,31 @@ void rbduckdb_init_value(void) {
     rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_hugeint", value_s__create_hugeint, 2);
     rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_uhugeint", value_s__create_uhugeint, 2);
     rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_decimal", value_s__create_decimal, 4);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_date", value_s__create_date, 3);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_time", value_s__create_time, 4);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_time_ns", value_s__create_time_ns, 4);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_time_tz", value_s__create_time_tz, 2);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_timestamp", value_s__create_timestamp, 7);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_timestamp_s", value_s__create_timestamp_s, 6);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_timestamp_ms", value_s__create_timestamp_ms, 7);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_timestamp_ns", value_s__create_timestamp_ns, 7);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_timestamp_tz", value_s__create_timestamp_tz, 1);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_interval", value_s__create_interval, 3);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_enum", value_s__create_enum, 2);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_union", value_s__create_union, 3);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_bit", value_s__create_bit, 1);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_bignum", value_s__create_bignum, 2);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_list", value_s__create_list, 2);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_array", value_s__create_array, 2);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_struct", value_s__create_struct, 2);
+    rb_define_private_method(rb_singleton_class(cDuckDBValue), "_create_map", value_s__create_map, 3);
     rb_define_singleton_method(cDuckDBValue, "create_null", value_s_create_null, 0);
-}
 
+    rb_define_method(cDuckDBValue, "list_size", value_list_size, 0);
+    rb_define_method(cDuckDBValue, "list_child", value_list_child, 1);
+    rb_define_method(cDuckDBValue, "struct_child", value_struct_child, 1);
+    rb_define_method(cDuckDBValue, "map_size", value_map_size, 0);
+    rb_define_method(cDuckDBValue, "map_key", value_map_key, 1);
+    rb_define_method(cDuckDBValue, "map_value", value_map_value, 1);
+    rb_define_method(cDuckDBValue, "to_ruby", value_to_ruby, 0);
+}

data/lib/duckdb/connection.rb

@@ -423,6 +423,25 @@ module DuckDB
       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+,

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)