duckdb 1.5.3.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/appender.rb

@@ -558,6 +558,29 @@ module DuckDB
       raise_appender_error('failed to append_uhugeint')
     end
 
+    # :call-seq:
+    #   appender.append_uuid(val) -> self
+    #
+    # Appends a UUID value to the current row in the appender.
+    # +val+ must be a String in canonical UUID format
+    # (<tt>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</tt>).
+    # Raises ArgumentError if +val+ is not a valid UUID string.
+    #
+    #   require 'duckdb'
+    #   db = DuckDB::Database.open
+    #   con = db.connect
+    #   con.query('CREATE TABLE uuids (id UUID)')
+    #   appender = con.appender('uuids')
+    #   appender
+    #     .append_uuid('550e8400-e29b-41d4-a716-446655440000')
+    #     .end_row
+    #     .flush
+    def append_uuid(value)
+      return self if _append_uuid(value)
+
+      raise_appender_error('failed to append_uuid')
+    end
+
     # call-seq:
     #   appender.append_date(val) -> self
     #

data/lib/duckdb/arrow_array_stream.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DuckDB
+  # The ArrowArrayStream class represents an exported Arrow C stream of a
+  # query result (Arrow C Data Interface). It is created by
+  # DuckDB::Result#arrow_c_stream and cannot be instantiated directly.
+  #
+  # The object satisfies the Ruby Arrow C stream protocol: #arrow_c_stream
+  # returns self and #to_i returns the address of the underlying
+  # <tt>struct ArrowArrayStream</tt>, so it can be consumed by ruby-polars,
+  # red-arrow and other Arrow consumers:
+  #
+  #   result = con.query('SELECT * FROM users')
+  #
+  #   # ruby-polars
+  #   df = Polars::DataFrame.new(result)
+  #
+  #   # red-arrow
+  #   reader = Arrow::RecordBatchReader.import(result.arrow_c_stream.to_i)
+  #
+  # The consumer takes ownership of the stream's contents; a result can be
+  # exported only once.
+  #
+  # [EXPERIMENTAL] This API is built on DuckDB's unstable Arrow C API and
+  # may change in any minor release.
+  class ArrowArrayStream
+    class << self
+      def new
+        raise DuckDB::Error, 'DuckDB::ArrowArrayStream cannot be instantiated directly. Use DuckDB::Result#arrow_c_stream.'
+      end
+    end
+  end
+end